lean-memory 0.1.0__py3-none-any.whl

lean_memory/types.py

@@ -0,0 +1,107 @@
+"""Core data types for lean-memory.
+
+These mirror the design-spec data model (episode / entity / fact). Phase 0 uses
+the fact layer with the monotemporal spine; the bi-temporal audit columns exist
+but are only populated when the `audit` extra is enabled (deferred past Phase 0).
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+def now_ms() -> int:
+    """Epoch milliseconds. Single source of wall-clock time so it can be faked in tests."""
+    return int(time.time() * 1000)
+
+
+def new_id() -> str:
+    """uuidv7-ish: time-sortable id. stdlib has no uuid7, so we prefix a ms timestamp.
+
+    Format: <48-bit ms hex>-<random>. Lexicographically sortable by creation time,
+    which matches the spec's "uuidv7 (time-sortable)" intent for episode/fact ids.
+    """
+    return f"{now_ms():012x}-{uuid.uuid4().hex[:16]}"
+
+
+@dataclass
+class Episode:
+    """Provenance layer: the verbatim ingested message/turn/JSON."""
+
+    namespace: str
+    raw: str
+    t_ref: int  # reference (world) time for relative-date resolution, epoch ms
+    source: str = "user"  # 'user'|'assistant'|'tool'|'doc'
+    id: str = field(default_factory=new_id)
+    created_at: int = field(default_factory=now_ms)
+
+
+@dataclass
+class Entity:
+    """Canonical entity (person/org/place/...). Phase 0 resolves by (namespace, name, type)."""
+
+    namespace: str
+    name: str
+    type: Optional[str] = None
+    summary: Optional[str] = None
+    resolved_id: Optional[str] = None  # canonical id if this row is an alias
+    id: str = field(default_factory=new_id)
+    created_at: int = field(default_factory=now_ms)
+
+
+@dataclass
+class Fact:
+    """A typed, timestamped triple with surface text — the unit of memory & retrieval.
+
+    The monotemporal spine (`valid_at`/`valid_to`/`superseded_by`/`is_latest`) is
+    always populated. Bi-temporal audit columns default to mirroring ingest time
+    and are only meaningfully diverged when the audit extra is on (Phase >0).
+    """
+
+    namespace: str
+    subject_id: str
+    predicate: str
+    fact_text: str  # standalone sentence — what gets embedded + reranked
+    valid_at: int  # world/event time the fact became true (epoch ms)
+    episode_id: str
+
+    object_id: Optional[str] = None  # null if object is a literal
+    object_literal: Optional[str] = None
+
+    valid_to: Optional[int] = None  # world time it stopped being true; None = still holds
+    superseded_by: Optional[str] = None
+    is_latest: int = 1
+
+    # bi-temporal audit axis (opt-in)
+    ingested_at: int = field(default_factory=now_ms)
+    expired_at: Optional[int] = None
+    invalidated_by: Optional[str] = None
+
+    # scoring / governance
+    confidence: float = 1.0
+    salience: float = 0.0
+    last_access: Optional[int] = None
+    access_count: int = 0
+    is_inference: int = 0
+    tier: str = "hot"  # 'hot'|'cold'
+
+    id: str = field(default_factory=new_id)
+    created_at: int = field(default_factory=now_ms)
+
+
+@dataclass
+class RetrievedFact:
+    """A fact returned from retrieval, with the scores that ranked it (for debugging/eval)."""
+
+    fact: Fact
+    final_score: float
+    relevance: float  # reranker (or fused) score
+    recency: float
+    importance: float
+    # provenance of the score, so the harness can ablate arms
+    dense_rank: Optional[int] = None
+    sparse_rank: Optional[int] = None
+    rrf_score: Optional[float] = None

lean_memory-0.1.0.dist-info/METADATA

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: lean-memory
+Version: 0.1.0
+Summary: Embedded, local-first agent memory with hybrid retrieval and ADD-only supersession.
+Project-URL: Homepage, https://github.com/Wuesteon/lean-memory
+Project-URL: Repository, https://github.com/Wuesteon/lean-memory
+Author: lean-memory
+License: Apache-2.0
+Keywords: agent-memory,embeddings,llm,local-first,mcp,memory,rag,retrieval,sqlite,vector-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database :: Database Engines/Servers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: bm25s>=0.2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: sqlite-vec>=0.1.6
+Provides-Extra: bench
+Requires-Dist: openai>=1.40; extra == 'bench'
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Provides-Extra: examples
+Requires-Dist: anthropic>=0.25; extra == 'examples'
+Provides-Extra: extract
+Requires-Dist: gliner2>=1.3.1; extra == 'extract'
+Provides-Extra: llm
+Requires-Dist: ollama>=0.6.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: models
+Requires-Dist: sentence-transformers>=3.0; extra == 'models'
+Requires-Dist: torch>=2.2; extra == 'models'
+Description-Content-Type: text/markdown
+
+# lean-memory
+
+[![test](https://github.com/Wuesteon/lean-memory/actions/workflows/test.yml/badge.svg)](https://github.com/Wuesteon/lean-memory/actions/workflows/test.yml)
+
+Embedded, local-first agent memory. No server, no daemon, no mandatory cloud key.
+
+> **Status (2026-07):** working toward the first public launch (MCP-first).
+> Roadmap and rationale: `docs/superpowers/specs/2026-07-08-strategic-direction-design.md`.
+> Public benchmark runs (LongMemEval/LoCoMo) are deferred until after launch;
+> the harness is complete (`bench/phase2_*.py`) and the engine flaws it exposed
+> are fixed on this branch — see `docs/phase2-learnings.md`.
+
+```python
+from lean_memory import Memory
+
+mem = Memory(root="./data")
+
+mem.add("user-42", "I work at Acme Corp.")
+mem.add("user-42", "I now work at Globex.")          # supersedes Acme automatically
+
+mem.search("user-42", "where does the user work?")   # → "I now work at Globex."
+```
+
+![lean-memory quickstart](docs/assets/quickstart.gif)
+
+Facts are extracted from natural language, stored in a per-namespace SQLite file, and retrieved with hybrid dense+sparse search. Old facts are never deleted — they're superseded and queryable at any past point in time.
+
+## Install
+
+```bash
+pip install lean-memory
+```
+
+Runs fully offline out of the box. Optional extras unlock real model quality:
+
+| Extra | What it adds |
+|---|---|
+| `lean-memory[models]` | Real embedder + reranker (Qwen3-0.6B + Ettin-32M) |
+| `lean-memory[extract]` | GLiNER2 candidate generation for richer extraction |
+| `lean-memory[llm]` | Ollama-backed LLM typing pass |
+| `lean-memory[mcp]` | MCP server bridge for Claude Desktop / Claude Code |
+| `lean-memory[examples]` | Terminal demo agent (requires `anthropic` SDK) |
+
+## Quickstart
+
+```python
+from lean_memory import Memory
+
+mem = Memory(root="./data")   # one SQLite file per namespace, stored under ./data/
+
+# Store facts in natural language
+mem.add("alice", "I work at Stripe.")
+mem.add("alice", "I now work at Vercel.")   # supersedes Stripe automatically
+
+# Retrieve — the superseded Stripe fact drops out; only the current one is returned
+results = mem.search("alice", "what does Alice do for work?", k=3)
+for hit in results:
+    print(hit.fact.fact_text, hit.final_score)
+# → I now work at Vercel. 0.89
+
+# Point-in-time query — what was true at a specific moment?
+mem.search("alice", "employer", as_of=1_700_000_000_000, is_latest_only=False)  # epoch ms
+
+# Always close when done (flushes WAL)
+mem.close()
+```
+
+## Demo Agent
+
+A terminal chatbot showing the full memory loop — add, retrieve, supersede, restart:
+
+```bash
+pip install 'lean-memory[examples]'
+export ANTHROPIC_API_KEY=sk-ant-...
+python examples/chat.py                  # uses offline stubs by default
+python examples/chat.py --namespace bob  # separate memory tenant, persists across restarts
+```
+
+No API key? The demo still runs — it echoes the retrieved memory context instead of calling Claude, so you can watch the engine work offline.
+
+## MCP Server — memory for Claude Code / Claude Desktop
+
+Give any MCP agent persistent local memory: three tools (`memory_add`,
+`memory_search`, `memory_clear`), one SQLite file per namespace, nothing
+leaves your machine.
+
+```bash
+pip install 'lean-memory[mcp,models,extract]'
+```
+
+> First run downloads three open models (~2.0 GB total: Qwen3-Embedding-0.6B
+> + Ettin-32M reranker for retrieval, plus GLiNER2-base (~0.8 GB) for real
+> extraction — all ungated). Pre-warm once so your MCP client never waits on
+> a download:
+>
+> ```bash
+> python -c "from lean_memory.embed.sentence_transformer import SentenceTransformerEmbedder; \
+> from lean_memory.retrieve.rerank import CrossEncoderReranker; \
+> SentenceTransformerEmbedder().embed_one('warm'); CrossEncoderReranker().score('warm', ['up']); \
+> from lean_memory.extract.gliner_extractor import Gliner2Generator; from lean_memory.types import Episode; \
+> Gliner2Generator().generate(Episode(namespace='w', raw='I work at Acme.', t_ref=0, source='user'))"
+> ```
+
+**Claude Code:**
+
+```bash
+claude mcp add lean-memory -- lean-memory-mcp
+```
+
+**Claude Desktop** — add to `mcpServers` (or copy `examples/mcp_config.json`):
+
+```json
+{ "lean-memory": { "command": "lean-memory-mcp", "env": { "LM_DATA_ROOT": "~/.lean_memory" } } }
+```
+
+Data root: `LM_DATA_ROOT` (default `~/.lean_memory`). Works offline-only too —
+the server opportunistically upgrades each backend that its extra is installed
+for (`[models]` → real embedder + reranker, `[extract]` → GLiNER2 extraction)
+and otherwise falls back to deterministic stub backends (fine for CI,
+semantically meaningless for real use — install `[mcp,models,extract]`).
+
+> **What the optional `[llm]` extra buys.** The canonical `[mcp,models,extract]`
+> install has no LLM typing pass, so the ~15% of candidates that escalate —
+> almost all of them inferential (`derives`) facts — are typed by a
+> deterministic stub instead of a model. Assertional facts are unaffected;
+> inference-type facts are effectively second-class on the default path. Adding
+> `[llm]` (a local Ollama model) upgrades that escalated tier to real
+> constrained typing. See ARCHITECTURE.md → Known Limitations.
+
+## Real Model Quality
+
+The default backends are offline stubs — deterministic and dependency-free, but semantically meaningless. Swap in real models for production-quality retrieval:
+
+```bash
+pip install 'lean-memory[models]'
+```
+
+With `Qwen3-Embedding-0.6B` + `Ettin-32M` reranker, retrieval jumps from 1/5 to 4/5 on the internal benchmark with zero code changes.
+
+> For benchmark results, architecture decisions, and implementation status see [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## How It Works
+
+Each `mem.add()` call runs a 4-pass hybrid extraction pipeline:
+
+1. **Rules** — regex + dateparser for common predicates (`works_at`, `lives_in`, …)
+2. **GLiNER2** — open-vocabulary NER candidate generation (offline stub by default)
+3. **Router** — recall-biased escalation: low-confidence, coreference, and inferential (`derives`) facts escalate to the LLM pass
+4. **LLM typing** — constrained relation typing via a local Ollama model (stub by default)
+
+Contradiction detection runs cheap-first (slot match → cosine → token subsumption → LLM). Conflicting facts are superseded, not deleted — the old fact stays with `is_latest=False` and a `superseded_by` pointer.
+
+Retrieval fuses two-stage Matryoshka dense search (256-dim coarse KNN → 768-dim re-score) with BM25 sparse, applies RRF fusion, reranks with a cross-encoder, and scores with salience-decay (`0.6·relevance + 0.2·recency + 0.2·importance`).
+
+## Develop
+
+```bash
+git clone https://github.com/Wuesteon/lean-memory
+cd lean-memory
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+pytest -q    # full offline suite, no downloads
+```
+
+## Project Layout
+
+```
+src/lean_memory/
+  memory.py                   Memory facade — the public API
+  types.py                    Episode / Fact / RetrievedFact types
+  store/                      Store interface + SqliteStore (vec0 + FTS5)
+  embed/                      Embedder interface, FakeEmbedder, SentenceTransformer
+  extract/                    4-pass extraction pipeline
+  retrieve/                   Reranker interface, retrieval pipeline
+examples/
+  chat.py                     Terminal demo agent
+  mcp_config.json             Drop-in MCP client config
+tests/                        offline test suite
+bench/                        Retrieval quality + BET-2 ablation harnesses
+```
+
+## License
+
+Apache-2.0

lean_memory-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+lean_memory/__init__.py,sha256=639w69GsqoPvip3-tu7KojoX3zfDZznGfS8Pe0z8iRQ,494
+lean_memory/mcp_server.py,sha256=wc-hVUz8tLjfyVIcmgQ92jJCJeEkfGjzXdDZ1ygp5So,5491
+lean_memory/memory.py,sha256=2IfW3n1_heGUJPXNHT5h0afABJ1nWQVX927GzhF47oA,8993
+lean_memory/types.py,sha256=LobuNQLFtC4gKppnoql1ioVmUS7V9S0Jk3bRoAqM2jY,3428
+lean_memory/embed/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory/embed/base.py,sha256=nYX2S6wS0zi5dZx22N-IK_FgFTFTdKig3Iah6CmUXgU,1876
+lean_memory/embed/fake.py,sha256=75KGqTl5qTOOvUHDEytvJfGhRpjNSM6WUPaE3EsFrbc,1560
+lean_memory/embed/sentence_transformer.py,sha256=ByI67A9D8e1CXo3EfUle_PKqiHBUHOkMt9LHZ5oJz2k,2508
+lean_memory/extract/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory/extract/contradiction.py,sha256=RMQYh0v4ogEQzndlt11FN4A2WDfEf-Auq3o_8jTDWdE,16274
+lean_memory/extract/gliner_extractor.py,sha256=lA14FyU28SvGFHmS-ZzELRfrq3NJhcibrkN-rTxQhJ0,24868
+lean_memory/extract/llm_typer.py,sha256=dCAGhiEL3zXs8rN7-eRGEQ4gJiZB8ecnN5H5rmqaers,19914
+lean_memory/extract/router.py,sha256=Hkwj7ffLXjH1TSqmQC9LI7lzwdVk22ojuUQCDOLLj_4,19174
+lean_memory/extract/rules.py,sha256=FtiVBINzIG05pRg1Zz8tji0fBwVOqzgdny98Cflgi5Q,4742
+lean_memory/extract/salience.py,sha256=MMxl43EEkU2wgszDem0bENee3c0eEdQ8DoOiuR1RXU0,5538
+lean_memory/extract/taxonomy.py,sha256=VsHIrr6gqOJeC9O7vruKSK5I9klzAyyQRt3_PjQnRLc,11704
+lean_memory/retrieve/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory/retrieve/rerank.py,sha256=MenN2ILaEoFUblO8UyopOs6nCjwmdyUQmpAqdiQmloM,2237
+lean_memory/retrieve/retriever.py,sha256=LGnhJvluN_lQUrSNODooqSZfCG_fxm8gtVBqW7o5N94,4530
+lean_memory/store/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lean_memory/store/base.py,sha256=0d29EyETf9_rn1yEbzhEJS-2R1bs_FoBdk6wvt_AOuM,3093
+lean_memory/store/schema.py,sha256=_PFM0bgLYDE9XX3vHEnLiSyMSvJGDE47PwN6sCBPgQA,3352
+lean_memory/store/sqlite_store.py,sha256=AQs240oCnV_PIrKF1k8R3NK4KQp5yV5axF1kC8lhHjM,12485
+lean_memory-0.1.0.dist-info/METADATA,sha256=-0d_o7R8t7-c3PnbD0AJ9PLVKTbUeZl57f4zFj8ZIhQ,9417
+lean_memory-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+lean_memory-0.1.0.dist-info/entry_points.txt,sha256=jOeIrkE0Z2vwDHeP705UoeSvd7agD6cSuM4SNPRhtdA,64
+lean_memory-0.1.0.dist-info/RECORD,,

lean_memory-0.1.0.dist-info/WHEEL

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

lean_memory-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lean-memory-mcp = lean_memory.mcp_server:main