attractor-engine 0.0.1__tar.gz

attractor_engine-0.0.1/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: attractor-engine
+Version: 0.0.1
+Summary: A brain-inspired memory engine — contextual storage and associative retrieval
+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 :: 1 - Planning
+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
+Description-Content-Type: text/markdown
+
+# attractor
+
+A brain-inspired memory engine — contextual storage and associative retrieval.
+
+**This package is under active development. Not yet functional.**
+
+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.
+
+```bash
+attractor start     # start the service
+attractor connect   # verify connection
+```
+
+## Status
+
+Early development. Watch this repo for updates.
+
+## Source
+
+[github.com/aag1091-alt/attractor](https://github.com/aag1091-alt/attractor)

attractor_engine-0.0.1/README.md

@@ -0,0 +1,22 @@
+# attractor
+
+A brain-inspired memory engine — contextual storage and associative retrieval.
+
+**This package is under active development. Not yet functional.**
+
+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.
+
+```bash
+attractor start     # start the service
+attractor connect   # verify connection
+```
+
+## Status
+
+Early development. Watch this repo for updates.
+
+## Source
+
+[github.com/aag1091-alt/attractor](https://github.com/aag1091-alt/attractor)

attractor_engine-0.0.1/STRUCTURE.md

@@ -0,0 +1,214 @@
+# Attractor — Phase 1 Service Structure
+
+## Directory Layout
+
+```
+attractor/
+├── attractor/                   # core package
+│   ├── __init__.py
+│   ├── main.py                  # FastAPI app + server entrypoint
+│   ├── config.py                # service config (port, db url, model name)
+│   │
+│   ├── models/                  # data models (Pydantic)
+│   │   ├── __init__.py
+│   │   ├── memory.py            # Memory, ContextFrame, MemoryResponse
+│   │   └── query.py             # SearchQuery, SearchResponse
+│   │
+│   ├── store/                   # storage abstraction
+│   │   ├── __init__.py
+│   │   ├── base.py              # MemoryStore interface
+│   │   └── pg_store.py          # PostgreSQL + pgvector implementation
+│   │
+│   ├── embeddings/              # embedding model wrapper
+│   │   ├── __init__.py
+│   │   └── encoder.py           # sentence-transformers loader + encode()
+│   │
+│   └── api/                     # route handlers
+│       ├── __init__.py
+│       ├── memories.py          # POST /memories, GET /memories/:id
+│       └── search.py            # POST /memories/search
+│
+├── cli.py                       # attractor start / attractor connect
+├── pyproject.toml               # dependencies + package config
+└── README.md
+```
+
+---
+
+## Data Models
+
+### ContextFrame
+The situational state at the time a memory was formed. Not metadata — retrieval key.
+
+```python
+class ContextFrame(BaseModel):
+    topic: str | None           # what was being discussed
+    entities: list[str]         # who/what was involved
+    task: str | None            # what was being done
+    session_id: str | None      # which session this came from
+```
+
+### Memory (write)
+```python
+class Memory(BaseModel):
+    content: str                # the memory text
+    context: ContextFrame       # situational state
+    tags: list[str] = []        # optional labels
+```
+
+### MemoryRecord (stored)
+```python
+class MemoryRecord(BaseModel):
+    id: str                     # uuid
+    content: str
+    context: ContextFrame
+    tags: list[str]
+    created_at: datetime
+    accessed_at: datetime
+    access_count: int           # foundation for Phase 3 decay
+    vector: list[float]         # embedding (not returned in API responses)
+```
+
+---
+
+## API Endpoints
+
+```
+POST   /memories                 write a memory
+GET    /memories/:id             get by ID
+POST   /memories/search          query by content + context filters
+DELETE /memories/:id             remove a memory
+
+GET    /health                   service health check
+```
+
+### POST /memories
+```json
+// request
+{
+  "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"]
+}
+
+// response
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "created_at": "2026-04-03T18:00:00Z"
+}
+```
+
+### POST /memories/search
+```json
+// request
+{
+  "query": "where did we land on auth token storage",
+  "context_filter": {
+    "topic": "security review"
+  },
+  "limit": 5
+}
+
+// response
+{
+  "results": [
+    {
+      "id": "550e8400...",
+      "content": "auth tokens should never be stored in localStorage",
+      "context": { ... },
+      "score": 0.91,
+      "created_at": "2026-04-03T18:00:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## Storage Layer
+
+### MemoryStore interface (base.py)
+```python
+class MemoryStore(ABC):
+    @abstractmethod
+    def write(self, record: MemoryRecord) -> str: ...
+
+    @abstractmethod
+    def get(self, id: str) -> MemoryRecord | None: ...
+
+    @abstractmethod
+    def search(self, vector: list[float], context_filter: dict, limit: int) -> list[MemoryRecord]: ...
+
+    @abstractmethod
+    def delete(self, id: str) -> bool: ...
+```
+
+### PostgreSQL + pgvector implementation (pg_store.py)
+- One table: `memories`
+- Schema mirrors MemoryRecord — content, context fields (JSONB), vector (pgvector), timestamps, access_count
+- Search: pgvector ANN (`<=>` cosine operator) + WHERE filters on context JSONB fields
+- Runs as a service alongside Attractor — no embedded DB
+
+---
+
+## Embedding Layer
+
+```python
+# encoder.py
+from sentence_transformers import SentenceTransformer
+
+class Encoder:
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2"):
+        self.model = SentenceTransformer(model_name)
+
+    def encode(self, text: str) -> list[float]:
+        return self.model.encode(text).tolist()
+```
+
+Model downloaded once on first run, cached locally. No API calls.
+
+---
+
+## CLI
+
+```bash
+attractor start                      # start service (default port 7747)
+attractor start --port 8000          # custom port
+attractor start --db postgresql://localhost/attractor  # custom db url
+attractor connect                    # ping /health, confirm service is up
+```
+
+Port 7747 — "loci" on a phone keypad. Keeping it.
+
+---
+
+## Dependencies (pyproject.toml)
+
+```
+fastapi
+uvicorn
+asyncpg                         # async PostgreSQL driver
+pgvector                        # pgvector Python client
+sentence-transformers
+numpy
+pydantic
+click                           # CLI
+```
+
+---
+
+## Phase 1 Complete When
+
+- [ ] `attractor start` boots the service
+- [ ] `attractor connect` confirms it's running
+- [ ] Can write a memory with a context frame via POST /memories
+- [ ] Can retrieve by ID via GET /memories/:id
+- [ ] Can search by content query via POST /memories/search
+- [ ] Context fields filter search results
+- [ ] Data persists across service restarts
+- [ ] Works on macOS, Linux, and Windows

attractor_engine-0.0.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "attractor-engine"
+version = "0.0.1"
+description = "A brain-inspired memory engine — contextual storage and associative retrieval"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+  { name = "aag1091-alt" }
+]
+keywords = ["memory", "database", "associative", "hopfield", "contextual", "ai", "agents", "attractor"]
+classifiers = [
+  "Development Status :: 1 - Planning",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Database",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/aag1091-alt/attractor"
+Repository = "https://github.com/aag1091-alt/attractor"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/attractor"]

attractor_engine-0.0.1/src/attractor/__init__.py

@@ -0,0 +1,6 @@
+__version__ = "0.0.1"
+
+raise ImportError(
+    "attractor is under active development and not yet functional. "
+    "Watch https://github.com/aag1091-alt/attractor for updates."
+)