Metadata-Version: 2.4
Name: attractor-engine
Version: 0.1.0
Summary: A Hopfield Network-based memory engine that stores and retrieves contextual memory the way a brain does — but fast.
Project-URL: Homepage, https://github.com/aag1091-alt/attractor
Project-URL: Repository, https://github.com/aag1091-alt/attractor
Author: aag1091-alt
License: MIT
Keywords: agents,ai,associative,attractor,contextual,database,hopfield,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: click>=8.1.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy<2.0.0,>=1.26.0
Requires-Dist: pgvector>=0.3.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: sentence-transformers>=2.7.0
Requires-Dist: uvicorn[standard]>=0.29.0
Description-Content-Type: text/markdown

# attractor

A Hopfield Network-based memory engine that stores and retrieves contextual memory the way a brain does — but fast.

Attractor is a standalone memory service purpose-built for storing and retrieving contextual memory. It is designed to work like a brain — not like a key-value store or a vector database.

Named after the concept of **attractors** in dynamical systems: stored memories are energy minima, retrieval is gradient descent to the nearest basin. Give it a partial or noisy cue and it converges to the full memory.

## Install

```bash
pip install attractor-engine
```

## Usage

### Start the service

```bash
attractor start                                      # default port 7747
attractor start --port 8000                          # custom port
attractor start --db postgresql://localhost/attractor  # custom db url
attractor connect                                    # verify service is running
```

### Write a memory

```bash
curl -X POST http://localhost:7747/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "auth tokens should never be stored in localStorage",
    "context": {
      "topic": "security review",
      "entities": ["auth", "frontend team"],
      "task": "reviewing PR #42",
      "session_id": "abc123"
    },
    "tags": ["security", "auth"]
  }'
```

### Retrieve by ID

```bash
curl http://localhost:7747/memories/<id>
```

### Search

```bash
curl -X POST http://localhost:7747/memories/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "where did we land on auth token storage",
    "context_filter": { "topic": "security review" },
    "limit": 5
  }'
```

## Requirements

- Python 3.10+
- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector) extension

## Status

Phase 1 complete — storage, retrieval, and semantic search are working.
Phases 2–4 (association graph, decay, Hopfield retrieval) are in development.

## Source

[github.com/aag1091-alt/attractor](https://github.com/aag1091-alt/attractor)
