lean-memory 0.1.0__tar.gz

lean_memory-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build distributions
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

lean_memory-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,43 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: test-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.os }} · py${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # Provision Python via uv (python-build-standalone). Unlike
+      # actions/setup-python, these builds are compiled with loadable-sqlite
+      # extensions enabled, which sqlite-vec needs to load — the macOS
+      # setup-python builds are not, so extension loading fails there.
+      # One code path for both OSes.
+      - name: Set up uv + Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      # setup-uv with a python-version input already provisions and activates a
+      # venv (it exports VIRTUAL_ENV), so no explicit `uv venv` step is needed —
+      # the install below targets that activated environment.
+      - name: Install (editable, dev + mcp extras)
+        run: uv pip install -e '.[dev,mcp]'
+
+      - name: Run offline test suite
+        run: uv run pytest tests/ -q

lean_memory-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.superpowers/
+bench/.phase2_cache/

lean_memory-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,208 @@
+# lean-memory — Architecture & Status
+
+Implementation status, design decisions, benchmark results, and known limitations.
+
+---
+
+## Implementation Status
+
+### Phase 0 — Storage & Retrieval
+
+| Component | Status | Notes |
+|---|---|---|
+| `Store` interface | ✅ | single abstraction; `SqliteStore` is the only impl |
+| `SqliteStore` (vec0 + FTS5) | ✅ | one file per namespace (per-tenant isolation) |
+| Monotemporal spine | ✅ | `valid_at`/`valid_to` + `is_latest` + ADD-only `superseded_by`; nothing is ever deleted |
+| Two-stage Matryoshka dense | ✅ | coarse 256-dim KNN → exact 768-dim re-score |
+| BM25 sparse arm | ✅ | FTS5 `bm25()` |
+| RRF fusion (k=10) | ✅ | `Σ 1/(10 + rank)` |
+| Mandatory rerank | ✅ | `IdentityReranker` (offline default) / `CrossEncoderReranker` (Ettin-32M) |
+| Salience-decay re-score | ✅ | `0.6·rel + 0.2·recency + 0.2·importance`, `recency = exp(-λ·age)` |
+| as-of temporal query | ✅ | world-time interval predicate |
+| Pluggable embedder | ✅ | `FakeEmbedder` (offline) / `SentenceTransformerEmbedder` (Qwen3-0.6B) |
+
+### Phase 1 — Hybrid Extraction
+
+| Component | Status | Notes |
+|---|---|---|
+| Relation taxonomy | ✅ | `asserts`/`supersedes`/`extends`/`derives`; single shared `Candidate` contract |
+| Pass 2 — candidate generation | ✅ | `StubCandidateGenerator` (offline) / `Gliner2Generator` (GLiNER2, `[extract]` extra) |
+| Pass 3 — recall-biased router | ✅ | escalates low-conf / endpoint-scoped coref / possible-`derives` (2026-07 re-freeze: `prior_entity` trigger dropped — see "Escalation recalibration") |
+| Pass 4 — LLM constrained typing | ✅ | `StubTyper` (offline) / `OllamaTyper` (local model, `[llm]` extra) |
+| Contradiction → supersession | ✅ | cheap-then-escalate: slot → cosine → subsumption → LLM |
+| Salience at write | ✅ | deterministic heuristic, rated once + cached on the `Fact` |
+| BET-2 ablation harness | ✅ | `bench/bet2_ablation.py` — **BET-2 PASS**; re-frozen 2026-07 at `(typing=0.4, conf=0.4)` (−0.4pp delta, 7.6% escalation), superseding the 2026-06-21 freeze — see "Escalation recalibration (2026-07)" below |
+
+### Phase 1 — Integrations
+
+| Component | Status | Notes |
+|---|---|---|
+| MCP server | ✅ | `memory_add` / `memory_search` / `memory_clear` via FastMCP (stdio transport) |
+| Terminal demo agent | ✅ | `examples/chat.py` — full add→retrieve→supersede loop with Claude |
+
+### Phase 2 — Next
+
+| Item | Status |
+|---|---|
+| Public benchmarks (LongMemEval / LoCoMo + frozen judge) | ⬜ deferred (post-launch) — harness complete, see `docs/superpowers/specs/2026-07-08-strategic-direction-design.md` |
+| int8 vector storage | ⬜ blocked — sqlite-vec 0.1.9 insert path is broken upstream |
+| `LanceStore` scale tier | ⬜ |
+
+---
+
+## Measured Performance
+
+### Retrieval Quality (BET-1 evidence)
+
+| Configuration | Top-1 | What it proves |
+|---|---|---|
+| Offline stubs (FakeEmbedder + IdentityReranker) | **1/5** | plumbing routes facts end-to-end (random vectors → chance result) |
+| Real (Qwen3-Embedding-0.6B + Ettin-32M), 5-fact set | **4/5** | real models lift quality with zero code changes |
+| Real, clean 3-fact set | **3/3** @ ~0.69 | the one toy-set miss was a small-corpus vocabulary artifact |
+
+The pluggable-backend architecture is validated. These are sanity checks on small hand-built sets — a publishable quality claim needs LongMemEval/LoCoMo + a frozen judge (Phase 2).
+
+Note: `google/embeddinggemma-300m` is a gated HF repo requiring license-accept. `Qwen3-Embedding-0.6B` is ungated and the stronger retrieval model (MTEB-R 64.65 vs 62.49) — use it instead.
+
+### Extraction Quality — BET-2 (2026-06-21, n=97)
+
+> **Superseded by the 2026-07 re-freeze** at operating point
+> `(typing=0.4, conf=0.4)` — see "Escalation recalibration (2026-07)" below.
+> The 2026-06-21 run below stays as the original PASS record; the frozen
+> constants and escalation rate quoted here (`conf 0.5`-era, 10.1%) are historical.
+
+**Metric A — Typer (`asserts` vs `derives`):**
+
+| Arm | macro-F1 | derives-recall |
+|---|---|---|
+| 100%-LLM (qwen2.5:3b) | 0.474 [0.27, 0.68] | 0.20 |
+| hybrid (StubTyper on direct bucket) | 0.474 [0.27, 0.68] | 0.20 |
+
+**Metric B — Resolver (`asserts`/`extends`/`supersedes`) with real embeddings:**
+
+| Arm | macro-F1 |
+|---|---|
+| both arms | **0.897** [0.73, 1.00] |
+
+**Gate results:**
+
+| Gate | Target | Result | Verdict |
+|---|---|---|---|
+| 1 — F1 delta (hybrid vs LLM, direct bucket) | ≤ 3pp | 0.0pp [0, 0] | ✅ PASS |
+| 2 — escalation rate (Wilson upper) | < 20% | 10.1% [5.2%, 18.7%] | ✅ PASS |
+| 3 — hybrid derives-recall not worse | ≥ LLM − 10pp | 0.20 ≥ 0.10 | ✅ PASS |
+
+**BET-2 = PASS** (goldset sha256 `350b18b51a97fe57`).
+
+### Escalation recalibration (2026-07)
+
+The Phase 2 ingest surfaced that BET-2's <20% escalation gate held only on clean
+goldset sentences: on **real LongMemEval conversational turns** the router routed
+**95.9%** of candidates to the LLM (baseline probe, `bench/results/calibration/2026-07-escalation-baseline.json`;
+best point typing=conf=0.3, 971/1012). Two confidence-independent router floors
+drove it — `coreference` 65.6% and `prior_entity` 54.8% — so no threshold pair
+could reach the target. Both were retired at the router:
+
+- **Endpoint-scoped coref/ellipsis** — the pronoun/demonstrative scan narrowed
+  from the whole `fact_text` to the predicate endpoints. On real turns
+  `coreference` collapsed **664 → 1** (`2026-07-granularity-sweep.json`).
+- **`prior_entity` trigger dropped** (two user-approved amendments: subject-only,
+  then removed entirely) — subject re-mention of a known entity is normal
+  discourse, not a hard case, and it stayed at 52.8% of real candidates even
+  scoped to the subject (`2026-07-escalation-postfix.json`). Entity linking is
+  deterministic by name; ambiguous refs still escalate via `coreference`,
+  inferential edges via `derives`.
+
+Post-drop probe on real turns (8 namespaces / 192 turns / 704 candidates,
+`2026-07-escalation-postdrop-p{1..4}.json`) selected the operating point:
+
+| typing | conf | escalated/seen | rate | by_reason |
+|---:|---:|---:|---:|---|
+| **0.40** | **0.40** | **103/704** | **14.6%** | derives 102, coref 1 |
+| 0.50 | 0.50 | 316/704 | 44.9% | pre_flagged 247, low_conf 247, derives 102, coref 1 |
+
+Only `(0.4, 0.4)` clears the margin (raising either threshold to 0.5 pulls in the
+247 candidates with model confidence in [0.4, 0.5)); the residual is
+derives-dominated (the irreducible inferential edges the LLM must own).
+
+**Granularity** (`2026-07-granularity-sweep.json`): GLiNER `DEFAULT_THRESHOLD`
+0.1 → 0.4 cut over-generation **8.43 → 3.67 facts/turn** (decision rule: smallest
+swept threshold meeting facts/turn ≤ 4). The `median_fact_len ≤ 160` target was
+waived (user-approved) as threshold-insensitive — it sits at 171–187 chars across
+the entire sweep, so no GLiNER threshold moves it.
+
+**Re-frozen constants:** `DEFAULT_TYPING_THRESHOLD = 0.4`, router
+`conf_threshold = 0.4`, `FROZEN_CONF_THRESHOLD = FROZEN_TYPING_THRESHOLD = 0.4`
+(`bench/bet2_goldset.py`). **BET-2 three-gate revalidation at the frozen point
+(`bench/bet2_ablation.py --real`, full output `2026-07-bet2-revalidation.txt`):**
+
+| Gate | Target | Result | Verdict |
+|---|---|---|---|
+| 1 — direct-bucket paired F1 delta | upper ≤ 3.0pp | −0.4pp [−1.2, +0.0]pp | ✅ PASS |
+| 2 — escalation rate (goldset, Wilson upper) | < 20% | 7.6% [3.5%, 15.6%] | ✅ PASS |
+| 3 — hybrid derives-recall not worse | ≥ LLM − 10pp | 0.20 ≥ 0.10 | ✅ PASS |
+
+**BET-2 re-freeze = PASS** (all three gates jointly). Metric B resolver macro-F1
+unchanged at **0.897** (the router change touches only the typer/direct path).
+
+---
+
+## Bugs Found by the Benchmark
+
+The measurement process found 4 real engine bugs before they shipped.
+
+| # | Bug | Fix |
+|---|---|---|
+| 1 | **`extends` unreachable** — every non-identical object mapped to `supersedes` | Additive signal routing: additive cues ("also", multi-valued predicates) → `extends`; functional slots still supersede |
+| 2 | **Resolver thresholds miscalibrated** — `HIGH=0.82`/`LOW=0.55` put Qwen3 refinements in the wrong band | Recalibrated to `HIGH=0.80`/`LOW=0.45`; verified 4/4 on real Qwen3 |
+| 3 | **`OllamaTyper` label-set mismatch** — offering all 4 relations to a typer with no prior-slot context caused qwen2.5:3b to anchor on `extends` for everything | Constrained to `{asserts, derives}` |
+| 4 | **Router `prior_entity` over-escalation** — "user" always in `known_entities` after turn 1, causing 73.7% false escalation | `self_entity` exemption in `_references_prior_entity()`; expanded `_KNOWN_PREDICATES`; gold set rebalanced 37→97 cases — **superseded 2026-07:** the `prior_entity` trigger was dropped entirely after real-turn data showed it still fired on 52.8% of candidates (see "Escalation recalibration (2026-07)") |
+
+---
+
+## Design Decisions
+
+### ADD-only writes / supersession
+
+Facts are never deleted or updated in place. A contradicting fact marks the old one `is_latest=False` via a `superseded_by` pointer and inserts the new one. This makes the full history auditable and enables point-in-time queries (`as_of=<timestamp_ms>`).
+
+### Offline-first with pluggable backends
+
+Every component has an offline stub that needs zero downloads and produces deterministic output. Real models are opt-in extras. This means the full offline test suite runs in seconds with no network access, and the architecture is validated independently of model availability.
+
+### Cheap-then-escalate contradiction detection
+
+The resolver tries slot match → cosine similarity → token subsumption before calling the LLM. Each step is ~100× cheaper than the next. Only genuinely ambiguous cases (high cosine, disjoint tokens) reach the LLM. The BET-2 gate 2 verifies the escalation rate stays under 20%.
+
+### Per-namespace SQLite files
+
+Each namespace (e.g. per-user) gets its own SQLite file rather than a shared database with a namespace column. This gives hard write isolation, trivial backup/export (copy one file), and clean multi-tenant semantics with no cross-tenant query risk.
+
+---
+
+## Known Limitations
+
+- **No benchmark-grade quality claim.** All numbers are on small hand-built sets. A real claim needs LongMemEval/LoCoMo + a frozen judge (Phase 2, deferred post-launch).
+- **Recency on historical corpora — addressed (2026-07).** `exp(-λ·age)` collapses to ~0 for every fact when historical data is read years later, so the 0.2 recency term was dead weight on such corpora. `Memory.search(now=...)` now forwards an explicit search-time anchor so callers evaluating historical data can restore the recency signal; the wall-clock default is unchanged for live use.
+- **Vectors stored float32, not int8.** sqlite-vec 0.1.9's int8 insert path is broken upstream. Flip when fixed (~0.2pt quality cost per BET-1, no correctness impact).
+- **Inference typing is second-class without `[llm]`.** On the default `[mcp,models,extract]` path there is no Ollama typer, so the ~15% of candidates that escalate — almost entirely inferential (`derives`) facts — fall through to the deterministic `StubTyper` rather than a model. Assertional facts are unaffected; inference-type facts are second-class until you add the `[llm]` extra, which routes that escalated tier through real constrained typing.
+- **Small-model ceiling.** qwen2.5:3b caps Typer accuracy. A larger local model would likely lift derives-recall. Untested.
+- **Single machine, single run** for all real numbers. Reproducible, but not multi-seed/multi-judge as the spec's BET-5 demands.
+
+---
+
+## Reproduce
+
+```bash
+# Offline (full suite, no downloads)
+pip install -e '.[dev]' && pytest -q
+
+# Real retrieval quality
+pip install -e '.[models]'
+python bench/smoke_quality.py --real --embedder Qwen/Qwen3-Embedding-0.6B
+
+# Real BET-2 ablation
+pip install -e '.[models,extract,llm]'
+ollama serve & ollama pull qwen2.5:3b
+python bench/bet2_ablation.py --real --decodes 3
+```

lean_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to lean-memory are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-12
+
+First public release. lean-memory is an embedded, local-first agent-memory
+engine: one SQLite file per namespace, hybrid dense+sparse retrieval with
+rerank, and ADD-only supersession queryable at any past point in time
+(`as_of`). No server, no daemon, no mandatory cloud key.
+
+### Added
+
+- **MCP server** exposing memory as three tools (`memory_add`, `memory_search`,
+  `memory_clear`) for Claude Code, Claude Desktop, and other MCP clients.
+  Canonical install `pip install 'lean-memory[mcp,models,extract]'`
+  opportunistically upgrades each backend whose extra is present (real embedder
+  + reranker via `[models]`, GLiNER2 extraction via `[extract]`) and otherwise
+  falls back to deterministic offline stubs. Two-minute quickstart with
+  copy-paste Claude Code / Claude Desktop config and a demo GIF.
+- **`Memory.search(now=...)`** — recency decay now anchors to a caller-supplied
+  timestamp, so the 0.2 recency term is no longer dead on historical corpora.
+- **Point-in-time queries** via `as_of` (epoch ms) with `is_latest_only=False`.
+- **CI + release workflows** (GitHub Actions): offline test matrix on
+  ubuntu/macOS × Python 3.10/3.13, plus build-and-publish to PyPI on `v*` tag
+  via Trusted Publishing.
+- PyPI metadata: keywords, classifiers, and project URLs.
+
+### Changed
+
+- **Default embedder is now the ungated Qwen3-Embedding-0.6B** (was a gated
+  Gemma model that broke the `[models]` first run). Reranker default is
+  Ettin-32M; both are pinned ungated and covered by regression tests.
+- **Escalation engine recalibrated on real conversational turns.** Endpoint-
+  scoped coreference/ellipsis detection replaces the whole-text pronoun scan
+  (coreference escalations dropped from 65.6% to effectively nil on real
+  turns), and the `prior_entity` trigger was retired (subject re-mention is
+  normal discourse, measured at 52.8% of candidates). At the re-frozen
+  `(typing_threshold=0.4, conf_threshold=0.4)` operating point, escalation on
+  the real LongMemEval probe is **14.6%** (was ~96% pre-fix), with the residual
+  being irreducible inferential-edge (`derives`) escalations. BET-2 three-gate
+  revalidation PASSes at this operating point.
+- **Extraction granularity calibrated** — GLiNER candidate threshold set to
+  0.4, cutting the extractor from ~8 facts/turn to ~3.7 so `fact_text` reads as
+  facts rather than whole utterances.
+- MCP server loads models lazily (first tool call rather than import) so a
+  cold-cache spawn answers the MCP handshake immediately instead of blocking on
+  a model download; search output is deduplicated.
+
+### Fixed
+
+- Sparse BM25 retrieval arm now honors the `as_of` interval predicate.
+- Known-entities handed to the router/typer are capped at the 100 most recent.
+
+[0.1.0]: https://github.com/Wuesteon/lean-memory/releases/tag/v0.1.0

lean_memory-0.1.0/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+## ⚠️ START HERE: strategy is quality-gate → MCP launch (2026-07-08)
+
+Approved direction: **close a small, hard quality gate on the first-run
+experience, then launch across MCP channels** (Pure A). Read before any work:
+
+1. **`docs/superpowers/specs/2026-07-08-strategic-direction-design.md`** — the
+   approved strategy (positioning, the six-item quality gate, launch plan, the
+   six-week post-launch demand read). Non-negotiable context; do not re-derive.
+2. **`docs/superpowers/plans/2026-07-08-launch-quality-gate.md`** — the ordered
+   implementation plan that executes the gate.
+
+State: the former "Phase 2 suspended, fix engine then re-run benchmarks" framing
+is **superseded**. Engine-fix backlog items 1–3 are **FIXED** on `launch-gate`
+(numbers are the source of truth in `bench/results/calibration/README.md`):
+
+- **Escalation recalibration** — endpoint-scoped coref + `prior_entity` trigger
+  dropped (two user-approved amendments); real-turn escalation **95.9% → 14.6%**
+  at the frozen `(typing=0.4, conf=0.4)` operating point; goldset **10.1% → 7.6%**.
+  BET-2 revalidation PASSES all three gates.
+- **Extraction granularity** — GLiNER `DEFAULT_THRESHOLD` 0.1 → 0.4;
+  **8.43 → 3.67 facts/turn**.
+- **Recency anchoring** — `Memory.search(now=...)` forwards search-time now
+  (wall-clock default unchanged).
+
+**Benchmark runs (LongMemEval/LoCoMo) are DEFERRED past the MCP launch** per the
+spec — they are a post-launch credibility layer, not the critical path. The
+harness (`bench/phase2_*.py`) is complete and needs no changes for the eventual
+re-run.
+
+**Remaining next steps = launch execution** per spec §3 (MCP Registry listing,
+`awesome-mcp-servers` PR, Claude Code plugin marketplace, PyPI polish, Show HN,
+subreddit posts); security housekeeping (rotate the OpenRouter key + HF token,
+merge the harness branch) is gate item 5.
+
+Historical context (dated, do not re-derive): `docs/phase2-learnings.md`
+(assumptions vs. reality postmortem) and `docs/superpowers/phase2-HANDOFF.md`
+(operational runbook + the now-fixed engine-fix backlog).
+
+## Project
+
+lean-memory: embedded, local-first agent-memory engine (SQLite vec0 + FTS5,
+hybrid retrieval + rerank, ADD-only supersession with a monotemporal spine).
+See `ARCHITECTURE.md` for the phase roadmap and BET results; `README.md` for
+the user-facing quickstart.
+
+- Python ≥3.10; dev venv at `.venv` (3.13). Run tests:
+  `.venv/bin/python -m pytest tests/ -q` (offline by default — all model
+  backends have deterministic stubs).
+- Real model extras are opt-in: `[models]` (embedder+reranker), `[extract]`
+  (GLiNER2), `[llm]` (Ollama typer), `[bench]` (OpenRouter client).
+- Benchmarks live in `bench/` (BET-2: `bet2_*.py`; Phase 2: `phase2_*.py`).
+  Frozen-config discipline: any number without a pinned config hash, judge
+  model, judge prompt, and backbone is not publishable.
+- Roadmap work is clustered into worktree-sized packets with dependencies,
+  gates, and file-conflict lanes: `docs/superpowers/workpackets.md`. Claim a
+  packet there before starting it; one worktree per packet.

lean_memory-0.1.0/PERFORMANCE.md

@@ -0,0 +1,3 @@
+# lean-memory — Performance
+
+Benchmark results, implementation status, and design decisions have moved to [ARCHITECTURE.md](ARCHITECTURE.md).

lean_memory-0.1.0/PKG-INFO

@@ -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