agent-memory-engine 0.1.0__tar.gz

agent_memory_engine-0.1.0/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "Bash(pip3 list:*)",
+      "Bash(.venv/bin/python -m pytest:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(ls:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(/Users/xjf/Public/Code/Agent-Project/.venv/bin/python3 -m pytest:*)",
+      "Bash(wc:*)",
+      "Bash(python3:*)"
+    ]
+  },
+  "disabledMcpjsonServers": [
+    "apple-notes"
+  ]
+}

agent_memory_engine-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e .[dev]
+      - run: pytest -q
+

agent_memory_engine-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+*.db
+*.db-*
+*.sqlite
+*.sqlite-*
+.env
+.DS_Store

agent_memory_engine-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 xjf
+
+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.
+

agent_memory_engine-0.1.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: agent-memory-engine
+Version: 0.1.0
+Summary: Zero-config, traceable, MCP-native long-term memory for agents.
+Project-URL: Homepage, https://github.com/xjf/agent-memory
+Project-URL: Repository, https://github.com/xjf/agent-memory
+Project-URL: Issues, https://github.com/xjf/agent-memory/issues
+Project-URL: Documentation, https://github.com/xjf/agent-memory/tree/main/docs
+Author: xjf
+License: MIT
+License-File: LICENSE
+Keywords: agent,llm,mcp,memory,rag,sqlite
+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
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Provides-Extra: api
+Requires-Dist: fastapi>=0.115.0; extra == 'api'
+Requires-Dist: uvicorn>=0.30.0; extra == 'api'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# agent-memory
+
+![CI](https://github.com/xjf/agent-memory/actions/workflows/ci.yml/badge.svg)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+Zero-config, traceable, MCP-native long-term memory for agents.
+
+`agent-memory` targets a gap in the current memory stack: a local-first engine that works with `pip install`, runs on pure SQLite, and makes memory evolution explainable instead of opaque.
+
+PyPI distribution name: `agent-memory-engine`
+
+## Why this exists
+
+- `Mem0` proves demand, but pulls in heavier infra such as Neo4j or Qdrant.
+- Local agents and personal copilots need a memory layer that is easy to embed, debug, export, and ship.
+- Interviews love this surface area: storage, retrieval, ranking, decay, provenance, conflict handling, MCP, and evaluation.
+
+## Current Status
+
+- SQLite backend with WAL, FTS5, audit log, evolution log, entity index, and causal parent links
+- Schema indexes for type, layer, recency, trust, source, relation, and audit hot paths
+- Python SDK via `MemoryClient`
+- Rule-based intent router with Reciprocal Rank Fusion
+- Adaptive forgetting utilities with dual-threshold layer transitions
+- Heuristic conflict detection with contradiction edges and trust-score adjustment
+- Optional LLM-backed conflict adjudication for top semantic candidates
+- Governance helpers for health reports, audit reads, and JSONL export/import
+- Optional MCP server and REST API adapters with dependency-friendly fallbacks
+- `sqlite-vec` integration with safe fallback to Python cosine scan when unavailable
+- Deterministic local fallback embeddings for testability and zero-friction startup
+- LLM-first conversation extraction with heuristic fallback
+- Trace graph reports with ancestors, descendants, relations, and evolution history
+- Idempotent maintenance cycle for decay, promotion/demotion, conflict upkeep, and consolidation
+- Benchmark helpers and LOCOMO-Lite style starter data
+
+## Quickstart
+
+```bash
+pip install -e .[dev]
+.venv/bin/python -m pytest -q
+```
+
+```bash
+agent-memory store "User prefers SQLite for local-first agents." --source-id demo
+agent-memory search "Why SQLite?"
+agent-memory health
+```
+
+```python
+from agent_memory import MemoryClient
+
+client = MemoryClient()
+item = client.add(
+    "The user prefers SQLite for local-first agent projects.",
+    source_id="demo-session",
+)
+
+results = client.search("What database does the user prefer?")
+print(results[0].item.content)
+
+trace = client.trace_graph(item.id)
+print(trace.descendants)
+
+health = client.health()
+print(health.suggestions)
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    A["Python SDK / CLI"] --> B["MemoryClient"]
+    C["MCP Server"] --> B
+    D["REST API"] --> B
+    B --> E["Intent Router"]
+    B --> F["Conflict Detector"]
+    B --> G["Trust Scorer"]
+    B --> H["Forgetting Engine"]
+    E --> I["SQLite Backend"]
+    F --> I
+    G --> I
+    H --> I
+    I --> J[("SQLite + FTS5 + sqlite-vec")]
+```
+
+### Core components
+
+- `src/agent_memory/client.py` — high-level SDK entry point
+- `src/agent_memory/storage/sqlite_backend.py` — SQLite persistence, FTS, vector fallback, trace queries
+- `src/agent_memory/controller/router.py` — intent-aware retrieval routing and RRF fusion
+- `src/agent_memory/controller/forgetting.py` — Ebbinghaus-inspired adaptive forgetting
+- `src/agent_memory/controller/conflict.py` — contradiction detection and conflict records
+- `src/agent_memory/controller/consolidation.py` — overlap grouping and merge-draft generation
+- `src/agent_memory/controller/trust.py` — multi-factor trust scoring
+- `src/agent_memory/governance/health.py` — stale/orphan/conflict monitoring
+- `src/agent_memory/interfaces/mcp_server.py` — eight MCP tools
+- `src/agent_memory/extraction/pipeline.py` — conversation-to-memory extraction
+- `benchmarks/` — storage/retrieval microbenchmarks and synthetic eval seeds
+
+### Design choices
+
+- **SQLite + WAL** keeps deployment zero-config while fitting agent workloads: many reads, occasional writes.
+- **Rule routing over LLM routing** keeps routing latency predictable and testable.
+- **RRF instead of score averaging** avoids calibration problems across lexical, entity, and semantic retrieval.
+- **`sqlite-vec` plus fallback** gives C/SQL vector search when available while keeping the package runnable everywhere.
+- **Soft delete** preserves provenance and causal trace integrity.
+- **Hash fallback embeddings** make the package runnable even before a local embedding model is available.
+- **Unique relation edges** keep maintenance idempotent and health metrics stable.
+
+## Project layout
+
+```text
+agent-memory/
+├── docs/plans/
+├── examples/
+├── src/agent_memory/
+│   ├── controller/
+│   ├── embedding/
+│   ├── extraction/
+│   └── storage/
+└── tests/
+```
+
+## Benchmarks
+
+Synthetic LOCOMO-Lite run on the bundled starter dataset (`30` dialogues / `150` questions):
+
+| Metric | `agent-memory` | Semantic-only baseline |
+|--------|----------------|------------------------|
+| Overall hit rate | 50.0% | 23.3% |
+| Factual recall | 53.3% | 6.7% |
+| Temporal recall | 36.7% | 3.3% |
+| Causal recall | 53.3% | 6.7% |
+| p95 retrieval latency | 16.64ms | 11.50ms |
+
+- Full report: `docs/benchmark-results.md`
+- Re-run locally: `python benchmarks/locomo_lite/evaluate.py`
+
+## MCP Usage
+
+Install MCP support and launch the stdio server:
+
+```bash
+pip install -e .[mcp]
+python -m agent_memory.interfaces.mcp_server
+```
+
+Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "python",
+      "args": ["-m", "agent_memory.interfaces.mcp_server"],
+      "env": {
+        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/default.db"
+      }
+    }
+  }
+}
+```
+
+Typical tools:
+
+- `memory_store` — store a memory with provenance
+- `memory_search` — run intent-aware retrieval
+- `memory_trace` — inspect causal ancestry and evolution
+- `memory_health` — inspect stale/conflict/orphan metrics
+
+More details: `docs/mcp-integration.md`
+
+## Demos
+
+- `python examples/demo_cross_session.py --db /tmp/agent-memory-demo.db`
+- `python examples/interactive_chat.py --db chat_memory.db --provider none`
+- `python examples/mcp_server.py`
+
+## Release Notes
+
+- `benchmarks/locomo_lite/latest_results.json` is regenerated by the evaluation script
+- `docs/screenshots/` is reserved for verified MCP client screenshots
+- Update GitHub URLs if you publish under a different org/user
+- Delivery record and full tutorial: `docs/project-delivery-and-tutorial.md`
+- Expansion and optimization review: `docs/plans/2026-03-24-agent-memory-expansion-review.md`
+
+## Dev Notes
+
+- Run all tests with `.venv/bin/python -m pytest -q`
+- Use the built-in CLI with `agent-memory --help`
+- `sqlite-vec` is installed as a package dependency; if the extension cannot be loaded at runtime, vector search safely falls back to Python cosine scan
+- Try microbenchmarks with `python benchmarks/bench_storage.py` and `python benchmarks/bench_retrieval.py`
+- Try the demo runner with `python examples/benchmark_runner.py`

agent_memory_engine-0.1.0/README.md

@@ -0,0 +1,194 @@
+# agent-memory
+
+![CI](https://github.com/xjf/agent-memory/actions/workflows/ci.yml/badge.svg)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+Zero-config, traceable, MCP-native long-term memory for agents.
+
+`agent-memory` targets a gap in the current memory stack: a local-first engine that works with `pip install`, runs on pure SQLite, and makes memory evolution explainable instead of opaque.
+
+PyPI distribution name: `agent-memory-engine`
+
+## Why this exists
+
+- `Mem0` proves demand, but pulls in heavier infra such as Neo4j or Qdrant.
+- Local agents and personal copilots need a memory layer that is easy to embed, debug, export, and ship.
+- Interviews love this surface area: storage, retrieval, ranking, decay, provenance, conflict handling, MCP, and evaluation.
+
+## Current Status
+
+- SQLite backend with WAL, FTS5, audit log, evolution log, entity index, and causal parent links
+- Schema indexes for type, layer, recency, trust, source, relation, and audit hot paths
+- Python SDK via `MemoryClient`
+- Rule-based intent router with Reciprocal Rank Fusion
+- Adaptive forgetting utilities with dual-threshold layer transitions
+- Heuristic conflict detection with contradiction edges and trust-score adjustment
+- Optional LLM-backed conflict adjudication for top semantic candidates
+- Governance helpers for health reports, audit reads, and JSONL export/import
+- Optional MCP server and REST API adapters with dependency-friendly fallbacks
+- `sqlite-vec` integration with safe fallback to Python cosine scan when unavailable
+- Deterministic local fallback embeddings for testability and zero-friction startup
+- LLM-first conversation extraction with heuristic fallback
+- Trace graph reports with ancestors, descendants, relations, and evolution history
+- Idempotent maintenance cycle for decay, promotion/demotion, conflict upkeep, and consolidation
+- Benchmark helpers and LOCOMO-Lite style starter data
+
+## Quickstart
+
+```bash
+pip install -e .[dev]
+.venv/bin/python -m pytest -q
+```
+
+```bash
+agent-memory store "User prefers SQLite for local-first agents." --source-id demo
+agent-memory search "Why SQLite?"
+agent-memory health
+```
+
+```python
+from agent_memory import MemoryClient
+
+client = MemoryClient()
+item = client.add(
+    "The user prefers SQLite for local-first agent projects.",
+    source_id="demo-session",
+)
+
+results = client.search("What database does the user prefer?")
+print(results[0].item.content)
+
+trace = client.trace_graph(item.id)
+print(trace.descendants)
+
+health = client.health()
+print(health.suggestions)
+```
+
+## Architecture
+
+```mermaid
+graph TD
+    A["Python SDK / CLI"] --> B["MemoryClient"]
+    C["MCP Server"] --> B
+    D["REST API"] --> B
+    B --> E["Intent Router"]
+    B --> F["Conflict Detector"]
+    B --> G["Trust Scorer"]
+    B --> H["Forgetting Engine"]
+    E --> I["SQLite Backend"]
+    F --> I
+    G --> I
+    H --> I
+    I --> J[("SQLite + FTS5 + sqlite-vec")]
+```
+
+### Core components
+
+- `src/agent_memory/client.py` — high-level SDK entry point
+- `src/agent_memory/storage/sqlite_backend.py` — SQLite persistence, FTS, vector fallback, trace queries
+- `src/agent_memory/controller/router.py` — intent-aware retrieval routing and RRF fusion
+- `src/agent_memory/controller/forgetting.py` — Ebbinghaus-inspired adaptive forgetting
+- `src/agent_memory/controller/conflict.py` — contradiction detection and conflict records
+- `src/agent_memory/controller/consolidation.py` — overlap grouping and merge-draft generation
+- `src/agent_memory/controller/trust.py` — multi-factor trust scoring
+- `src/agent_memory/governance/health.py` — stale/orphan/conflict monitoring
+- `src/agent_memory/interfaces/mcp_server.py` — eight MCP tools
+- `src/agent_memory/extraction/pipeline.py` — conversation-to-memory extraction
+- `benchmarks/` — storage/retrieval microbenchmarks and synthetic eval seeds
+
+### Design choices
+
+- **SQLite + WAL** keeps deployment zero-config while fitting agent workloads: many reads, occasional writes.
+- **Rule routing over LLM routing** keeps routing latency predictable and testable.
+- **RRF instead of score averaging** avoids calibration problems across lexical, entity, and semantic retrieval.
+- **`sqlite-vec` plus fallback** gives C/SQL vector search when available while keeping the package runnable everywhere.
+- **Soft delete** preserves provenance and causal trace integrity.
+- **Hash fallback embeddings** make the package runnable even before a local embedding model is available.
+- **Unique relation edges** keep maintenance idempotent and health metrics stable.
+
+## Project layout
+
+```text
+agent-memory/
+├── docs/plans/
+├── examples/
+├── src/agent_memory/
+│   ├── controller/
+│   ├── embedding/
+│   ├── extraction/
+│   └── storage/
+└── tests/
+```
+
+## Benchmarks
+
+Synthetic LOCOMO-Lite run on the bundled starter dataset (`30` dialogues / `150` questions):
+
+| Metric | `agent-memory` | Semantic-only baseline |
+|--------|----------------|------------------------|
+| Overall hit rate | 50.0% | 23.3% |
+| Factual recall | 53.3% | 6.7% |
+| Temporal recall | 36.7% | 3.3% |
+| Causal recall | 53.3% | 6.7% |
+| p95 retrieval latency | 16.64ms | 11.50ms |
+
+- Full report: `docs/benchmark-results.md`
+- Re-run locally: `python benchmarks/locomo_lite/evaluate.py`
+
+## MCP Usage
+
+Install MCP support and launch the stdio server:
+
+```bash
+pip install -e .[mcp]
+python -m agent_memory.interfaces.mcp_server
+```
+
+Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "agent-memory": {
+      "command": "python",
+      "args": ["-m", "agent_memory.interfaces.mcp_server"],
+      "env": {
+        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/default.db"
+      }
+    }
+  }
+}
+```
+
+Typical tools:
+
+- `memory_store` — store a memory with provenance
+- `memory_search` — run intent-aware retrieval
+- `memory_trace` — inspect causal ancestry and evolution
+- `memory_health` — inspect stale/conflict/orphan metrics
+
+More details: `docs/mcp-integration.md`
+
+## Demos
+
+- `python examples/demo_cross_session.py --db /tmp/agent-memory-demo.db`
+- `python examples/interactive_chat.py --db chat_memory.db --provider none`
+- `python examples/mcp_server.py`
+
+## Release Notes
+
+- `benchmarks/locomo_lite/latest_results.json` is regenerated by the evaluation script
+- `docs/screenshots/` is reserved for verified MCP client screenshots
+- Update GitHub URLs if you publish under a different org/user
+- Delivery record and full tutorial: `docs/project-delivery-and-tutorial.md`
+- Expansion and optimization review: `docs/plans/2026-03-24-agent-memory-expansion-review.md`
+
+## Dev Notes
+
+- Run all tests with `.venv/bin/python -m pytest -q`
+- Use the built-in CLI with `agent-memory --help`
+- `sqlite-vec` is installed as a package dependency; if the extension cannot be loaded at runtime, vector search safely falls back to Python cosine scan
+- Try microbenchmarks with `python benchmarks/bench_storage.py` and `python benchmarks/bench_retrieval.py`
+- Try the demo runner with `python examples/benchmark_runner.py`

agent_memory_engine-0.1.0/benchmarks/__init__.py

@@ -0,0 +1,2 @@
+__all__ = []
+

agent_memory_engine-0.1.0/benchmarks/bench_retrieval.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from pathlib import Path
+from statistics import mean
+import sys
+import time
+
+if __package__ in {None, ""}:
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from agent_memory import MemoryClient
+from agent_memory.config import AgentMemoryConfig
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+def build_client(num_memories: int = 500) -> MemoryClient:
+    backend = SQLiteBackend(":memory:")
+    client = MemoryClient(config=AgentMemoryConfig(database_path=":memory:"), backend=backend)
+    for index in range(num_memories):
+        client.add(
+            f"Project note {index}: SQLite, MCP, trust scoring, and traceability are important.",
+            source_id="bench-retrieval",
+            tags=["benchmark", "memory"],
+        )
+    return client
+
+
+def run_retrieval_benchmark(iterations: int = 100, num_memories: int = 500) -> dict[str, float]:
+    client = build_client(num_memories=num_memories)
+    latencies_ms: list[float] = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        client.search("Why does the project prefer SQLite and traceability?", limit=5)
+        latencies_ms.append((time.perf_counter() - start) * 1000)
+    latencies_ms.sort()
+    return {
+        "iterations": float(iterations),
+        "num_memories": float(num_memories),
+        "avg_latency_ms": mean(latencies_ms),
+        "p50_latency_ms": latencies_ms[int(len(latencies_ms) * 0.5)],
+        "p95_latency_ms": latencies_ms[int(len(latencies_ms) * 0.95)],
+        "p99_latency_ms": latencies_ms[min(len(latencies_ms) - 1, int(len(latencies_ms) * 0.99))],
+    }
+
+
+if __name__ == "__main__":
+    print(run_retrieval_benchmark())

agent_memory_engine-0.1.0/benchmarks/bench_storage.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from pathlib import Path
+from statistics import mean
+import sys
+import time
+
+if __package__ in {None, ""}:
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from agent_memory import MemoryClient
+from agent_memory.config import AgentMemoryConfig
+from agent_memory.storage.sqlite_backend import SQLiteBackend
+
+
+def run_storage_benchmark(num_memories: int = 1000) -> dict[str, float]:
+    backend = SQLiteBackend(":memory:")
+    client = MemoryClient(config=AgentMemoryConfig(database_path=":memory:"), backend=backend)
+    latencies_ms: list[float] = []
+    start = time.perf_counter()
+    for index in range(num_memories):
+        op_start = time.perf_counter()
+        client.add(
+            f"User preference #{index}: prefers deterministic local memory pipelines.",
+            source_id="bench-storage",
+            tags=["benchmark"],
+        )
+        latencies_ms.append((time.perf_counter() - op_start) * 1000)
+    total_seconds = time.perf_counter() - start
+    return {
+        "num_memories": float(num_memories),
+        "total_seconds": total_seconds,
+        "throughput_ops_per_sec": num_memories / total_seconds,
+        "avg_latency_ms": mean(latencies_ms),
+        "max_latency_ms": max(latencies_ms),
+    }
+
+
+if __name__ == "__main__":
+    print(run_storage_benchmark())

agent_memory_engine-0.1.0/benchmarks/locomo_lite/README.md

@@ -0,0 +1,29 @@
+# LOCOMO-Lite
+
+This folder contains a synthetic evaluation starter set for `agent-memory`.
+
+## Purpose
+
+- sanity-check long-context memory retrieval
+- compare full intent-aware routing against semantic-only retrieval
+- provide a reproducible benchmark for README and release notes
+
+## Files
+
+- `sample_dialogues.jsonl` — 30 multi-turn synthetic sessions
+- `sample_questions.jsonl` — 150 benchmark questions with expected answers
+- `evaluate.py` — benchmark runner
+
+## Evaluation Loop
+
+1. ingest each dialogue into `MemoryClient`
+2. run each question through `client.search()` in `full` mode
+3. run the same questions through a semantic-only baseline
+4. compute hit rate by intent and latency statistics
+
+## Run
+
+```bash
+.venv/bin/python benchmarks/locomo_lite/evaluate.py
+cat benchmarks/locomo_lite/latest_results.json
+```