agent-memory-engine 0.1.0__py3-none-any.whl

agent_memory_engine-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,39 @@
+agent_memory/__init__.py,sha256=HSRX66pMcisGFsAoue6Nzb_hrMxxzU9jQHUTt0d4_WU,628
+agent_memory/cli.py,sha256=A2cAo3Iszuq3QHTwRMGBrIyTcVRkginWjfcVNZzZ0PI,4876
+agent_memory/client.py,sha256=sYcmFpWTMwwE7WoEYZsqyysQR0O7EK2hp0urq6j1Ctc,15033
+agent_memory/config.py,sha256=NfKljannY0E8aYnleQSGfLQbCJcnT4j7qgt4N7ozfkw,1087
+agent_memory/models.py,sha256=K8mPuei4V0_IXV7Rmt9SP5B-FmEqI0j7C_Ko5FTeNE4,3589
+agent_memory/controller/__init__.py,sha256=WHJ-LdBeHavDUUmTQkQX5LSuWfuC1yIXvoxneHC-VuY,492
+agent_memory/controller/conflict.py,sha256=zlzHAkkL8_YYflEtZkG0zWoLkpm8v1rFztE-6d9hEmE,4407
+agent_memory/controller/consolidation.py,sha256=38IYe47V9XjtG6SCTQv4S1MRKLR-TSRy70AajwhXkOs,5714
+agent_memory/controller/forgetting.py,sha256=PXI10uWxhUPYJ0BhYHgWk8Jovx2tVgAs8UgqU0tslhc,1091
+agent_memory/controller/router.py,sha256=h-zIkcAhj8jntGCIwq9JPgY1dz971CI5llH_O2STk0o,2641
+agent_memory/controller/trust.py,sha256=2q9IjNpso50U3WHgOZeAjXJWKQJAPwuVWwDPRbM81tg,957
+agent_memory/embedding/__init__.py,sha256=Y1GMnUPHmJk1QPm1c2NvBUO42D9ARYmOf8_2v9cfTpQ,214
+agent_memory/embedding/base.py,sha256=jcBBce1tGvtzUjQHs9bo0amyOXQEsqoYch5leY2Eb2c,194
+agent_memory/embedding/local_provider.py,sha256=L5UPrpsvWmbBscfysvDtM6qEC7o6vHuJLCgBYSmYIqk,1315
+agent_memory/embedding/openai_provider.py,sha256=F49P0lNtluHnUpup4kFkyV4YSKgLau-Sve3mQcbumVU,396
+agent_memory/extraction/__init__.py,sha256=eYdqLD6jlG0xvdYl-XoV3wCOrh4q9q9Z0SiQZSbOU-A,203
+agent_memory/extraction/entity_extractor.py,sha256=p0fIt9_O3D4sU-z_QQeL66isTPbtnhc5J7fdy-hdHQU,419
+agent_memory/extraction/pipeline.py,sha256=p4Ka16sxdgPOcM2Ri09YItlNqTA9SrdOC4GBitU9GUA,5390
+agent_memory/extraction/prompts.py,sha256=1BvWGGtgjA6JazTHFy05-NCc7LWfNZ-hYzH68Q5E-E8,982
+agent_memory/governance/__init__.py,sha256=xWEvh7SHKVVaX8r7Tbqnev3G75JhPAP7zQ9Oh6GMrto,284
+agent_memory/governance/audit.py,sha256=jrzeGmHCU9O0qBv5DDwfmGTbi-vuYBEtOR4l0RH1r5o,333
+agent_memory/governance/export.py,sha256=vZCnsX4o6VDNcT4QXkE4ZPSU8NJikULpYhTM9xG6-MA,3036
+agent_memory/governance/health.py,sha256=uBSahLc_ETOn84-oN5lVh1STg0q4rwt5GMHEcl7Qeg0,1500
+agent_memory/interfaces/__init__.py,sha256=NWqq_EEUk26Hp30TloUXoz5KhzpA1T55AE93vc9Qpug,495
+agent_memory/interfaces/mcp_server.py,sha256=BC4msAyftAUa-qmSV6LXExlCrT2HiixNfT6WQPzOEHs,4370
+agent_memory/interfaces/rest_api.py,sha256=FCDyG2QS_Zx0Ghz6PeoFNCqEQzJitUPPIaSdUv8oJU4,2626
+agent_memory/llm/__init__.py,sha256=L5ZNMHgemLOmtToBu7SHXRRedC6wPyHYsI1U6UUrDWg,157
+agent_memory/llm/base.py,sha256=PsjyJo_MMFoZLUALH3mjHi4-AkXFNHRHhbErJdgog_Q,460
+agent_memory/llm/ollama_client.py,sha256=-jOcBz7TA5vC8GkOWr7cgdH1nxEXP-5Bbtg6OdPZPRU,2208
+agent_memory/llm/openai_client.py,sha256=gSUC0tWkfTgrbmVDbiNcAWH6Sm3ZwcQsC8sKYSkgDR4,3479
+agent_memory/storage/__init__.py,sha256=1XCHKO9y34HLHDaccq_9qOanGid88zOJe1JvFXBVuAA,92
+agent_memory/storage/base.py,sha256=Nt4eUT2ji59bT0bAUxIdoQvafXrh0GtePA6muiwPPD0,1624
+agent_memory/storage/schema.sql,sha256=cUCEh3kOrBWFEm3Xxblir8HOID4BymzznPxvFqzJuGA,4542
+agent_memory/storage/sqlite_backend.py,sha256=lNPnhSNz19CSx-3vo00IMYn3X1sAQLSRRezoSvjRing,29565
+agent_memory_engine-0.1.0.dist-info/METADATA,sha256=ttZd-4YS4YtBVNFzd0mr6D55McyZRv0zsk83-38iIE4,8509
+agent_memory_engine-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agent_memory_engine-0.1.0.dist-info/entry_points.txt,sha256=mG_BjBbd8UY1fAkTlcl2sByYvElm35FtvqUziRuI96Q,55
+agent_memory_engine-0.1.0.dist-info/licenses/LICENSE,sha256=75nagrRO1dKma_9mUWD0yXjDVoDPTTYKduoP9kp_Ums,1061
+agent_memory_engine-0.1.0.dist-info/RECORD,,

agent_memory_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_memory_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-memory = agent_memory.cli:main

agent_memory_engine-0.1.0.dist-info/licenses/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.
+