cortex-mem 1.0.0__tar.gz

cortex_mem-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dhawalc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortex_mem-1.0.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include requirements.txt
+include service/config.yaml
+include cortex/schema.sql
+recursive-include schemas *.yaml
+recursive-exclude index *
+recursive-exclude snapshots *
+recursive-exclude __pycache__ *

cortex_mem-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: cortex-mem
+Version: 1.0.0
+Summary: Always-On Memory Service with Progressive Disclosure (L0/L1/L2) and Weighted Retrieval
+Author-email: dhawalc <dhawal@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dhawalc/cortex-mem
+Project-URL: Repository, https://github.com/dhawalc/cortex-mem
+Project-URL: Issues, https://github.com/dhawalc/cortex-mem/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: chromadb>=0.4.0
+Requires-Dist: aiosqlite>=0.19.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# cortex-mem
+
+Always-On Memory Service with Progressive Disclosure (L0/L1/L2) and Weighted Retrieval.
+
+## Installation
+
+```bash
+pip install cortex-mem
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/dhawalc/cortex-mem.git
+cd cortex-mem
+pip install -e .
+```
+
+## Quick Start (30 seconds)
+
+```bash
+# Start service
+cortex-mem start --daemon
+
+# Check status
+cortex-mem status
+
+# Search memory
+cortex-mem search "deployment"
+
+# Stop service
+cortex-mem stop
+```
+
+## OpenClaw Integration
+
+cortex-mem auto-configures OpenClaw on install. No manual setup needed.
+
+```python
+from cortex_mem.openclaw_provider import CortexMemProvider
+
+async with CortexMemProvider() as mem:
+    await mem.log("achievement", "Task completed", "Successfully shipped v1")
+    results = await mem.search("deployment strategies")
+```
+
+## Features
+
+- **Weighted Memory** — Important memories surface automatically via reinforcement learning
+- **Progressive Disclosure** — 98% token reduction with L0/L1/L2 tiered retrieval
+- **4-Tier Architecture** — Episodic, Semantic, Procedural, and Working memory
+- **Cortex Engine** — Smart query with auto-escalation across disclosure levels
+- **HTTP API** — Simple REST endpoints for any language / agent framework
+
+## API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/memory/{tier}` | POST | Write a memory entry |
+| `/memory/search` | POST | Keyword search with weighted scoring |
+| `/memory/browse/{path}` | GET | Browse module tree |
+| `/memory/weight` | POST | Adjust entry weight (reinforcement) |
+| `/cortex/query` | POST | Smart query with L0/L1/L2 escalation |
+| `/cortex/documents` | GET | List indexed documents |
+| `/health` | GET | Service health check |
+
+## CLI
+
+```
+cortex-mem start [--port 9100] [--daemon]   Start service
+cortex-mem stop                              Stop service
+cortex-mem status                            Health check
+cortex-mem search QUERY [--limit 5]          Search memory
+cortex-mem migrate SOURCE                    Import workspace data
+```
+
+## Architecture
+
+```
+cortex-mem/
+├── cortex_mem/          # Python package + CLI
+│   ├── cli.py           # Click CLI entry point
+│   ├── openclaw_plugin.py
+│   └── openclaw_provider.py
+├── service/             # FastAPI application
+│   ├── api.py           # Endpoints
+│   ├── storage.py       # JSONL engine + weighted scoring
+│   ├── models.py        # Pydantic schemas
+│   └── client.py        # Async HTTP client
+├── cortex/              # Progressive disclosure engine
+│   ├── tiered_retrieval.py  # L0/L1/L2 query
+│   ├── tier_generator.py    # Document ingestion
+│   └── db.py            # SQLite metadata
+├── modules/             # Module tree (JSONL data)
+│   ├── memory/
+│   │   ├── episodic/    # experiences, decisions, failures
+│   │   ├── semantic/    # facts, relations
+│   │   └── procedural/  # skills, patterns
+│   ├── identity/        # Persona, values
+│   ├── operations/      # Workflows
+│   └── research/        # Papers, notes
+├── schemas/             # JSONL schema definitions
+├── setup.py
+├── pyproject.toml
+├── Dockerfile
+└── run.py               # Direct entry point
+```
+
+## Docker
+
+```bash
+docker build -t cortex-mem .
+docker run -p 9100:9100 cortex-mem
+```
+
+## License
+
+MIT

cortex_mem-1.0.0/README.md

@@ -0,0 +1,118 @@
+# cortex-mem
+
+Always-On Memory Service with Progressive Disclosure (L0/L1/L2) and Weighted Retrieval.
+
+## Installation
+
+```bash
+pip install cortex-mem
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/dhawalc/cortex-mem.git
+cd cortex-mem
+pip install -e .
+```
+
+## Quick Start (30 seconds)
+
+```bash
+# Start service
+cortex-mem start --daemon
+
+# Check status
+cortex-mem status
+
+# Search memory
+cortex-mem search "deployment"
+
+# Stop service
+cortex-mem stop
+```
+
+## OpenClaw Integration
+
+cortex-mem auto-configures OpenClaw on install. No manual setup needed.
+
+```python
+from cortex_mem.openclaw_provider import CortexMemProvider
+
+async with CortexMemProvider() as mem:
+    await mem.log("achievement", "Task completed", "Successfully shipped v1")
+    results = await mem.search("deployment strategies")
+```
+
+## Features
+
+- **Weighted Memory** — Important memories surface automatically via reinforcement learning
+- **Progressive Disclosure** — 98% token reduction with L0/L1/L2 tiered retrieval
+- **4-Tier Architecture** — Episodic, Semantic, Procedural, and Working memory
+- **Cortex Engine** — Smart query with auto-escalation across disclosure levels
+- **HTTP API** — Simple REST endpoints for any language / agent framework
+
+## API
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/memory/{tier}` | POST | Write a memory entry |
+| `/memory/search` | POST | Keyword search with weighted scoring |
+| `/memory/browse/{path}` | GET | Browse module tree |
+| `/memory/weight` | POST | Adjust entry weight (reinforcement) |
+| `/cortex/query` | POST | Smart query with L0/L1/L2 escalation |
+| `/cortex/documents` | GET | List indexed documents |
+| `/health` | GET | Service health check |
+
+## CLI
+
+```
+cortex-mem start [--port 9100] [--daemon]   Start service
+cortex-mem stop                              Stop service
+cortex-mem status                            Health check
+cortex-mem search QUERY [--limit 5]          Search memory
+cortex-mem migrate SOURCE                    Import workspace data
+```
+
+## Architecture
+
+```
+cortex-mem/
+├── cortex_mem/          # Python package + CLI
+│   ├── cli.py           # Click CLI entry point
+│   ├── openclaw_plugin.py
+│   └── openclaw_provider.py
+├── service/             # FastAPI application
+│   ├── api.py           # Endpoints
+│   ├── storage.py       # JSONL engine + weighted scoring
+│   ├── models.py        # Pydantic schemas
+│   └── client.py        # Async HTTP client
+├── cortex/              # Progressive disclosure engine
+│   ├── tiered_retrieval.py  # L0/L1/L2 query
+│   ├── tier_generator.py    # Document ingestion
+│   └── db.py            # SQLite metadata
+├── modules/             # Module tree (JSONL data)
+│   ├── memory/
+│   │   ├── episodic/    # experiences, decisions, failures
+│   │   ├── semantic/    # facts, relations
+│   │   └── procedural/  # skills, patterns
+│   ├── identity/        # Persona, values
+│   ├── operations/      # Workflows
+│   └── research/        # Papers, notes
+├── schemas/             # JSONL schema definitions
+├── setup.py
+├── pyproject.toml
+├── Dockerfile
+└── run.py               # Direct entry point
+```
+
+## Docker
+
+```bash
+docker build -t cortex-mem .
+docker run -p 9100:9100 cortex-mem
+```
+
+## License
+
+MIT

cortex_mem-1.0.0/cortex/db.py

@@ -0,0 +1,135 @@
+"""
+SQLite metadata store for Cortex tiered documents.
+Thread-safe, async-compatible via aiosqlite.
+"""
+import json
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DB_PATH = Path(__file__).parent.parent / "index" / "cortex_tiers.db"
+SCHEMA_PATH = Path(__file__).parent / "schema.sql"
+
+
+def _get_conn(db_path: Path = DB_PATH) -> sqlite3.Connection:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    return conn
+
+
+def init_db(db_path: Path = DB_PATH) -> sqlite3.Connection:
+    conn = _get_conn(db_path)
+    with open(SCHEMA_PATH) as f:
+        conn.executescript(f.read())
+    conn.commit()
+    return conn
+
+
+def insert_document(conn: sqlite3.Connection, doc: Dict[str, Any]) -> str:
+    doc_id = doc.get("doc_id") or str(uuid.uuid4())
+    tags = json.dumps(doc.get("tags", []))
+    conn.execute(
+        """
+        INSERT OR REPLACE INTO documents (
+            doc_id, hierarchy_path, title, doc_type,
+            l0_abstract, l0_token_count,
+            l1_overview, l1_token_count,
+            l2_file_path, l2_token_count, l2_checksum,
+            chromadb_l0_id, chromadb_l1_id,
+            parent_path, depth, tags,
+            l0_generated_at, l1_generated_at,
+            source_type, cortex_tier
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            doc_id,
+            doc["hierarchy_path"],
+            doc["title"],
+            doc["doc_type"],
+            doc["l0_abstract"],
+            doc["l0_token_count"],
+            doc.get("l1_overview"),
+            doc.get("l1_token_count", 0),
+            doc["l2_file_path"],
+            doc.get("l2_token_count", 0),
+            doc["l2_checksum"],
+            doc.get("chromadb_l0_id"),
+            doc.get("chromadb_l1_id"),
+            doc.get("parent_path"),
+            doc.get("depth", 0),
+            tags,
+            doc.get("l0_generated_at"),
+            doc.get("l1_generated_at"),
+            doc.get("source_type", "manual"),
+            doc.get("cortex_tier"),
+        ),
+    )
+    conn.commit()
+    return doc_id
+
+
+def get_document(conn: sqlite3.Connection, doc_id: str) -> Optional[Dict[str, Any]]:
+    row = conn.execute("SELECT * FROM documents WHERE doc_id = ?", (doc_id,)).fetchone()
+    if row is None:
+        return None
+    return _row_to_dict(row)
+
+
+def get_all_documents(conn: sqlite3.Connection) -> List[Dict[str, Any]]:
+    rows = conn.execute("SELECT * FROM documents ORDER BY updated_at DESC").fetchall()
+    return [_row_to_dict(r) for r in rows]
+
+
+def search_by_hierarchy(
+    conn: sqlite3.Connection, prefix: str
+) -> List[Dict[str, Any]]:
+    rows = conn.execute(
+        "SELECT * FROM documents WHERE hierarchy_path LIKE ? ORDER BY hierarchy_path",
+        (prefix + "%",),
+    ).fetchall()
+    return [_row_to_dict(r) for r in rows]
+
+
+def mark_stale(conn: sqlite3.Connection, doc_id: str, reason: str):
+    conn.execute(
+        "UPDATE documents SET is_stale = 1, stale_reason = ? WHERE doc_id = ?",
+        (reason, doc_id),
+    )
+    conn.commit()
+
+
+def log_query(
+    conn: sqlite3.Connection,
+    query_text: str,
+    l0_results: int,
+    l1_expansions: int,
+    l2_loads: int,
+    total_tokens: int,
+    latency_ms: int,
+    agent_id: Optional[str] = None,
+):
+    conn.execute(
+        """
+        INSERT INTO query_log (query_id, query_text, agent_id,
+            l0_results, l1_expansions, l2_loads, total_tokens, latency_ms)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (str(uuid.uuid4()), query_text, agent_id,
+         l0_results, l1_expansions, l2_loads, total_tokens, latency_ms),
+    )
+    conn.commit()
+
+
+def _row_to_dict(row: sqlite3.Row) -> Dict[str, Any]:
+    d = dict(row)
+    if isinstance(d.get("tags"), str):
+        try:
+            d["tags"] = json.loads(d["tags"])
+        except (json.JSONDecodeError, TypeError):
+            d["tags"] = []
+    d["is_stale"] = bool(d.get("is_stale"))
+    return d

cortex_mem-1.0.0/cortex/schema.sql

@@ -0,0 +1,75 @@
+-- Cortex Tiered Retrieval — SQLite schema
+-- Equivalent to cortex_tiers PostgreSQL schema from master plan.
+-- Stores document metadata + L0/L1 content; L2 lives on filesystem.
+
+CREATE TABLE IF NOT EXISTS documents (
+    doc_id          TEXT PRIMARY KEY,
+    hierarchy_path  TEXT NOT NULL,
+    title           TEXT NOT NULL,
+    doc_type        TEXT NOT NULL CHECK (doc_type IN (
+        'strategy', 'backtest', 'research', 'episode',
+        'skill', 'pattern', 'session_learning', 'reference'
+    )),
+
+    -- Tier content
+    l0_abstract     TEXT NOT NULL,
+    l0_token_count  INTEGER NOT NULL,
+    l1_overview     TEXT,
+    l1_token_count  INTEGER DEFAULT 0,
+    l2_file_path    TEXT NOT NULL,
+    l2_token_count  INTEGER DEFAULT 0,
+    l2_checksum     TEXT NOT NULL,
+
+    -- ChromaDB references
+    chromadb_l0_id  TEXT,
+    chromadb_l1_id  TEXT,
+
+    -- Hierarchy
+    parent_path     TEXT,
+    depth           INTEGER DEFAULT 0,
+    tags            TEXT DEFAULT '[]',
+
+    -- Timestamps
+    created_at      TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at      TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    l0_generated_at TEXT,
+    l1_generated_at TEXT,
+
+    -- Invalidation
+    is_stale        INTEGER DEFAULT 0,
+    stale_reason    TEXT,
+
+    -- Source tracking
+    source_type     TEXT DEFAULT 'manual',
+    cortex_tier     TEXT CHECK (cortex_tier IN ('episodic', 'semantic', 'procedural') OR cortex_tier IS NULL)
+);
+
+CREATE INDEX IF NOT EXISTS idx_docs_hierarchy ON documents (hierarchy_path);
+CREATE INDEX IF NOT EXISTS idx_docs_parent ON documents (parent_path);
+CREATE INDEX IF NOT EXISTS idx_docs_type ON documents (doc_type);
+CREATE INDEX IF NOT EXISTS idx_docs_stale ON documents (is_stale) WHERE is_stale = 1;
+
+CREATE TABLE IF NOT EXISTS directories (
+    dir_id      TEXT PRIMARY KEY,
+    path        TEXT UNIQUE NOT NULL,
+    parent_path TEXT,
+    name        TEXT NOT NULL,
+    description TEXT,
+    doc_count   INTEGER DEFAULT 0,
+    created_at  TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    updated_at  TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_dirs_parent ON directories (parent_path);
+
+CREATE TABLE IF NOT EXISTS query_log (
+    query_id    TEXT PRIMARY KEY,
+    query_text  TEXT NOT NULL,
+    agent_id    TEXT,
+    l0_results  INTEGER DEFAULT 0,
+    l1_expansions INTEGER DEFAULT 0,
+    l2_loads    INTEGER DEFAULT 0,
+    total_tokens INTEGER DEFAULT 0,
+    latency_ms  INTEGER DEFAULT 0,
+    created_at  TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);