midas-memory 0.0.1__tar.gz

midas_memory-0.0.1/.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and fill in. Only needed for --openai (real embeddings / LLM-judge).
+OPENAI_API_KEY=
+
+# Optional: alternative providers (DeepSeek/Mistral/Grok are OpenAI-compatible).
+# OPENAI_BASE_URL=

midas_memory-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install (all extras + dev)
+        run: pip install ".[all,dev]"
+      - name: Run the suite
+        run: python -m pytest -q

midas_memory-0.0.1/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+
+# Environments
+.venv/
+venv/
+.env
+
+# uv
+uv.lock
+
+# Eval outputs
+results/
+*.local.json
+
+# OS / editor
+.DS_Store
+Thumbs.db
+
+# Large / downloadable benchmark datasets (fetched via the loader — see eval/datasets.py)
+data/longmemeval_s.json
+data/longmemeval_oracle.json
+data/longmemeval_m.json
+
+# Local uv cache (set via UV_CACHE_DIR for this project)
+.uv-cache/
+
+# Ad-hoc scratch
+/test_category_breakdown.py
+
+# Internal strategy / competitive / handoff docs — keep OUT of any public release
+_private/
+
+# Datasets are fetched locally via eval/datasets.py, never committed
+/data/

midas_memory-0.0.1/BENCHMARKS.md

@@ -0,0 +1,260 @@
+# Midas Benchmarks
+
+Honest, reproducible benchmarks for the Midas agentic-memory SDK. Every number here comes from a
+real run with the command to reproduce it. We deliberately **lead with reader-independent metrics**
+(retrieval + cost) and treat end-to-end answer correctness as a secondary, noisy signal — see
+*Methodology* for why that is the honest choice, not a convenient one.
+
+## TL;DR
+
+Midas isolates and wins the two axes that actually measure a *memory layer* (as opposed to the
+reader LLM stacked on top):
+
+- **Retrieval** — on LongMemEval-`s` (evidence buried among distractors), Midas retrieves the
+  supporting turns at **recall@k 0.95** vs a recency-window baseline's **0.03**.
+- **Cost** — Midas does **0 LLM calls, $0 API spend, and 0 data egress at ingest** (local embeddings
+  only), versus LLM-at-ingest memory systems that call an LLM per session to extract facts.
+
+## 1. Retrieval quality — `recall@k` (deterministic)
+
+Fraction of gold supporting turns retrieved into the context. Fully deterministic (local embeddings,
+no LLM), so it reproduces exactly.
+
+| dataset | setting | baseline-raw | **Midas** |
+|---|---|---:|---:|
+| **LongMemEval-`s`** (buried evidence, hard retrieval) | n=40, bge-base, no rerank, seed 0 | 0.03 | **0.95** |
+| **LoCoMo** (5 conversations) | n=50, bge-base, no rerank, seed 0 | 0.02 | **0.85** |
+
+Across **both** datasets Midas retrieves the supporting turns at **0.85–0.95** while a recency window
+gets **≤0.03** — the wedge holds beyond a single benchmark. On LongMemEval-`s` (n=40) the per-category
+recall@k is strong across the board: fact 0.89 · multi-session 0.97 · knowledge-update 1.00 ·
+temporal 0.95 · preference 1.00. A recency window finds essentially **none** of the buried evidence;
+Midas finds ~9 in 10 — exactly the multi-session setting where retrieval quality decides whether the
+answer is even *possible*. (`min_relevance` parsimony is a separate cost/quality knob; the numbers
+above are pure retrieval, no pruning.)
+
+**Time-aware retrieval (LLM-free).** Memories carry real **event time** (parsed from the dataset's
+session timestamps), so recency and chronological context reflect *when things happened*, not load
+order — the bitemporal signal long-horizon memory needs. Turning it on lifts **temporal recall@k
+0.86 → 0.95** (n=40, A/B via `--midas-no-time`), in line with the LongMemEval paper's +7–11% for
+temporal handling — but done with regex/relative-date math, **not** an LLM, preserving the no-LLM
+ingest/query edge. (fact dips 0.92 → 0.89, within n=13 noise and with no effect on fact *answer*.)
+
+```bash
+# reproduce (deterministic; downloads LongMemEval-s on first run)
+python -m eval.runner --dataset longmemeval --variant s --local \
+  --local-max-text-chars 600 --local-batch-size 16 --midas-no-rerank \
+  --max-questions 15 --limit 20 --seed 0
+```
+
+## 2. Cost / latency — the no-LLM edge (memory layer only)
+
+Measured with the runner's cost instrumentation; excludes the shared reader/judge LLM (identical
+across systems).
+
+| system | ingest ms/event | memory-layer LLM | API $ | data egress |
+|---|---:|---|---|---|
+| **Midas** | ~116 (cold) · ~0 (cached) | **0** | **$0** | **none** |
+| Mem0 *(LLM-at-ingest class)* | ~668 | ≥1 call / session | yes (per token) | yes (every turn) |
+
+Midas's ingest cost is pure local ONNX embedding. LLM-at-ingest systems (Mem0, and **Hindsight**,
+whose TEMPR extracts facts with an LLM at `retain` and CARA reasons with an LLM at `reflect`) pay an
+LLM call per ingested session — which means **$/token forever at scale, seconds of latency, and every
+conversation turn leaving the box**. At the scale where agent memory actually matters, that cost
+structure — not a few points of benchmark accuracy — is what decides build-vs-buy.
+
+**Microbenchmark (`eval/bench_perf.py`, bge-base on a modest CPU box — measured, not estimated):** a
+single `remember` is **~16 ms p50** on short records (embed-bound — there is no LLM, just the ONNX
+embedding forward pass; the time scales with text length, so the longer real turns above land at the
+~116 ms/event figure), `build_context` **~51 ms p50** over a 2,000-record store; ingest batches far
+faster via `remember_many`. Honest framing: these are **tens of milliseconds, embed-bound** — fast and local (no
+per-turn network round-trip), not sub-millisecond. **Footprint: ~3.6 MB per 1,000 records** at 768 dims
+— embeddings are stored as **float32 arrays**; a Python `list[float]` would cost ~7× more (~24 MB/1k),
+and switching to float32 left `recall@k` unchanged (LoCoMo 0.27 → 0.27). SQLite persistence already
+stored float32.
+
+```bash
+python -m eval.bench_perf --local --n 2000 --q 200   # latency · throughput · real (tracemalloc) footprint
+```
+
+**Every Midas mechanism is local, $0, zero-egress** — embeddings (bge-base ONNX), recall, supersession,
+the NLI contradiction/entailment checks (`midas/nli.py`, int8 ONNX MNLI), and the abstention metric.
+The only LLM is the *reader*, which is pluggable. **Demonstrated end-to-end fully offline** — Midas +
+a local `llama3.2:1b` reader/judge via Ollama (on a local GPU): LongMemEval-`s` n=10 → recall@k **0.80**,
+answer **0.40**, **0 API calls / $0 / nothing leaves the box**. (The modest answer rate is the 1B
+reader; a larger local model lifts it — correctness is reader-bound. The point: the pipeline is 100%
+local at zero marginal cost.)
+
+```bash
+# fully-local, $0, offline pipeline (local Ollama reader; no API key):
+ollama serve &   # then: ollama pull llama3.2:1b
+python -m eval.runner --dataset longmemeval --variant s --local --midas-no-rerank \
+  --judge --judge-ollama --judge-model llama3.2:1b --max-questions 10 --seed 0
+```
+
+```bash
+# reproduce (cold ingest cost: disable the embedding cache)
+python -m eval.runner --dataset longmemeval --variant s --local \
+  --no-local-embedding-cache --midas-no-rerank --max-questions 3 --limit 20 --seed 0
+```
+
+## 3. Provenance (auditability)
+
+`recall@k` is computable for Midas and the recency baseline because they return **source turn IDs**.
+It is **N/A for fact-synthesizing systems** (Mem0, Hindsight) — they return LLM-rewritten facts, not
+traceable sources. For Midas this is a feature: retrieved context is **auditable back to the exact
+source turn**, with no extraction-time LLM that can silently hallucinate. This matters for enterprise
+and compliance.
+
+## 4. Scaling — sub-linear search past the exact scan (ANN)
+
+The default `InMemoryStore` runs an **exact** cached cosine scan: O(N) per query but fast in absolute
+terms (~5 ms/query at 36k × 768-d; ~130–230 ms extrapolated to 1M). For larger corpora, `IVFStore`
+wraps a **numpy-only** inverted-file index — **no native dependency** (unlike faiss/hnswlib): the
+corpus is k-means-clustered into `nlist` cells and a query scans only the `nprobe` nearest cells, so
+search is **sub-linear**. `nprobe` tunes recall vs latency at query time, with no rebuild.
+
+Measured on the **36k real bge-base embeddings** cached from the runs above (k=10, 500 held-out
+queries — real embeddings cluster, which is IVF's intended regime; uniform-random vectors are its
+worst case):
+
+| nprobe | recall@10 vs exact | IVF ms/q | speedup vs exact |
+|---:|---:|---:|---:|
+| 1  | 0.52 | 0.13 | 37× |
+| 4  | 0.82 | 0.76 |  6× |
+| 8  | 0.91 | 1.49 |  3× |
+| 16 | 0.95 | 3.27 |  1.5× |
+
+The win **grows with N** (IVF scans ≈ `nprobe·√N` candidates vs exact's N): the exact↔IVF crossover
+is ~10k records, and at nprobe=8 the speedup rises 0×→1×→2×→3× across 5k→36k. Extrapolating by the
+candidate count, at **1M** records exact ≈ 130–230 ms vs IVF(nprobe=8) ≈ 8 ms — **~20× at recall
+~0.90**. Below ~10k the exact scan wins (clustering overhead dominates), which is why `InMemoryStore`
+stays the default and `IVFStore` is opt-in for large, read-heavy corpora.
+
+```bash
+python -m eval.bench_ann   # real cached embeddings if present, else synthetic clustered
+```
+
+## 5. Retention — selective forgetting beats recency (no LLM)
+
+Long-horizon memory must stay **bounded**. Midas forgets by `memory_value` (importance × recency); the
+real question is whether that keeps the *right* memories under pressure. Measured on **LongMemEval-`s`
+(n=40, evidence buried among distractors)** by evicting to a fixed budget and comparing policies
+(`eval/retention.py`, recall@k averaged over all 40 questions):
+
+| keep | importance — `StructuralImportance` | importance — `ContentImportance` | recency (FIFO) | random |
+|---|---:|---:|---:|---:|
+| 50% | **0.56** | 0.43 | 0.36 | 0.25 |
+| 25% | **0.36** | 0.26 | 0.19 | 0.12 |
+
+**Importance-ranked forgetting beats recency at every level** (`value > fifo > random`), and a structural
+salience signal (boost an *assertion of a durable attribute*; demote questions/meta) beats the plain
+content score by **+0.10–0.13 recall@k** under forgetting — all **no-LLM**. On undifferentiated chat
+(LoCoMo) the signal is neutral, because recall there doesn't gate on importance; the buried-fact setting
+is where it shows. (The honest negatives along the way — *novelty-vs-store* and *reinforcement* — are
+documented in the design doc; the moat is reporting them too.)
+
+```bash
+python -m eval.retention --dataset longmemeval --variant s --local --no-rerank \
+  --structural-importance --value-rank-only --max-questions 40 --fractions 0.5,0.25
+```
+
+## 6. Correctness with a fixed strong reader (secondary)
+
+`recall@k` measures the memory layer directly; *answer correctness* additionally depends on the reader
+LLM (see Methodology). Holding the reader **fixed and identical across systems** (`gpt-4.1-mini` at
+temp 0 — the same non-reasoning reader class the LongMemEval leaderboard uses), Midas's retrieval edge
+converts to a large answer edge:
+
+| dataset (reader = gpt-4.1-mini) | baseline-raw answer | **Midas** answer |
+|---|---:|---:|
+| LongMemEval-`s` (n=40, seed 0) | 0.05 | **0.82** |
+
+Per-category Midas answer (indicative, wide bars at n=4–13): fact **1.00** · knowledge-update **1.00** ·
+multi-session **0.89** · temporal **~0.64–0.82** (noisy) · preference 0.33. Same reader for both, so the
+~16× gap (0.82 vs 0.05) is the memory layer: a recency window almost never holds the buried evidence
+(recall@k 0.03), so the reader cannot answer.
+For scale, 2026 SOTA on LongMemEval is **reader-dominated and LLM-ingest-based**: Mastra Observational
+Memory scores **84.2% (gpt-4o) → 94.9% (gpt-5-mini)** — a +11pt swing from the *reader alone* — using
+an LLM Observer/Reflector at ingest; Mem0 ~94.4.
+
+**Reader sweep — same reader as SOTA, but Midas does ZERO LLM at ingest** (LongMemEval-`s`, n=40,
+seed 0; judge fixed = gpt-4o to match Observational Memory's protocol; structured answerer):
+
+| reader (Midas, no-LLM ingest) | **Midas** answer | Observational Memory (LLM ingest) |
+|---|---:|---:|
+| gpt-4o | **0.84** | 0.84 — **match** |
+| gpt-5-mini | 0.87–0.89 | 0.95 |
+
+**At gpt-4o, Midas ties the SOTA (0.84) with $0 LLM ingest** — OM gets the same number by running an
+LLM Observer+Reflector on every conversation at ingest. With gpt-5-mini Midas reaches 0.87–0.89 vs
+OM's 0.95: OM's curated observations help a strong reader more than raw retrieved turns do. Across the
+sweep Midas pays **$0 at ingest, no data egress, and returns source-traceable turns** — none of which
+the LLM-ingest systems offer — and its retrieval **scales to ~500-session corpora (LongMemEval-`m`) by
+retrieving + forgetting** (measured: a ~4,944-turn haystack assembles a bounded ~480-token context,
+recall@k 0.78 over n=3), where a keep-every-observation-in-context design does not fit by construction.
+*(We measure Midas's side at that scale; we do not run OM — the overflow is an architectural inference,
+not a head-to-head.)* By category Midas **leads
+multi-session (0.89 vs OM's 0.872)** and matches knowledge-update (1.00 vs 0.962); the remaining gap is
+**temporal** (0.82 vs 0.955; per-category n=4–13 → wide bars).
+
+A **structured answerer** (ask the reader to pull the relevant dated entries and do the date arithmetic
+before answering) lifts **non-reasoning** readers a lot — gpt-4o 0.76 → 0.84, multi-session 0.56 → 0.89
+— and is neutral for reasoning readers that already do this internally (gpt-5-mini 0.89 → 0.87, within
+noise). Since the cheap, deployable readers are the non-reasoning ones, it is on by default.
+
+**Time-awareness — measured on the deterministic metric.** The LLM-free event-time grounding lifts
+**temporal `recall@k` 0.86 → 0.95** (A/B via `--midas-no-time`, deterministic and reproducible) with
+no real regression elsewhere (multi-session holds at 0.97; fact 0.92 → 0.89 is within n=13 noise). Its
+effect on *answer* correctness is real in principle — the reader can resolve "how many days ago…" from
+the dated context + a "today" anchor — but at **n=11 per category the answer deltas are inside run-to-run
+judge noise** (the temporal answer alone bounced 0.64–0.82 across identical-config runs), so we do
+**not** quote a per-category answer lift. This is the methodology working as intended: trust `recall@k`,
+distrust small-n correctness deltas.
+
+**Caveat:** n=40 sample with gpt-4.1-mini; the published Zep/Mem0 numbers run their full systems over
+the full set with GPT-4o. Correctness also moves far more with the reader than with the memory layer
+(see Methodology) — a strong reader can still miss multi-hop reasoning even when recall@k is high (the
+evidence is present; the reasoning is the bottleneck). So we treat correctness as a secondary, wide-bar
+signal and lead with `recall@k`.
+
+```bash
+# reproduce (needs an LLM key; this used OpenRouter gpt-4.1-mini as reader + judge)
+JUDGE_PROVIDER=openrouter JUDGE_MODEL=openai/gpt-4.1-mini \
+python -m eval.runner --dataset longmemeval --variant s --local \
+  --local-max-text-chars 600 --local-batch-size 16 --midas-no-rerank \
+  --judge --max-questions 40 --limit 20 --seed 0      # add --midas-no-time for the A/B
+```
+
+## Methodology — why reader-independent metrics
+
+End-to-end "answer correctness" on these benchmarks is **dominated by the reader LLM, not the memory
+layer**:
+
+- Holding the reader fixed, a memory layer's lift is real; but swapping in a bigger reader moves the
+  *headline* far more than the memory does. (Public SOTA on LongMemEval reports ~39% → ~83% from the
+  memory system but ~83% → ~91% from *just a larger reader* — most of the headline is the reader.)
+- Our own hosted LLM judge (an MoE served via API) is **not reproducible across sessions**: identical
+  inputs scored ~0.46 one day and ~0.13 the next, even at temperature 0. We added a local,
+  seed-pinned, serialized judge (`--judge-ollama`) to make correctness reproducible, but a small local
+  reader is too weak to *use* good context — so correctness still does not cleanly isolate memory
+  quality.
+
+Therefore: **`recall@k` (deterministic, reader-independent) and ingest cost (structural) are our
+primary metrics.** We report correctness only with a fixed reader and wide error bars, and never as a
+headline.
+
+### Honest caveats
+- **Sample** is n=40 on LongMemEval-`s` and n=50 across 5 LoCoMo conversations. `recall@k` is
+  deterministic, so the sample is real; the full LongMemEval set / all 10 LoCoMo conversations would
+  tighten it further.
+- **Latency is hardware/provider-dependent** (the ~668 ms for the LLM-at-ingest class includes API
+  round-trip). The durable, hardware-independent claim is the **0-LLM / $0 / no-egress** column.
+- **baseline-raw** = "stuff recent turns into the window" (the naive big-context approach).
+- Numbers measured on CPU with `BAAI/bge-base-en-v1.5`. GPU / a faster embedder lowers Midas latency.
+- **Reranking is off by default on large haystacks.** A cross-encoder reranker is available, but on
+  LongMemEval-`s` (CPU) it added ~80× query latency (4.2 s vs 53 ms) with **no `recall@k` change**
+  (0.88 → 0.88): it reorders the records that already fit the budget (which can help the *reader*) but
+  does not change *which* evidence fits. So it is not on the retrieval-quality path here.
+
+*All commands run from the repo root. `recall@k` requires no API key; `--judge*` flags do.*

midas_memory-0.0.1/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+Notable changes to Midas. Pre-1.0 — the API may change. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+- **Core SDK** — `Memory` (`remember` / `recall` / `build_context` / `assemble`) ranking by
+  relevance × importance × recency, with same-thread neighbour-window expansion and budgeted,
+  highest-value-first context assembly. No LLM at ingest or query.
+- **Embedders** — `HashingEmbedder` (offline, zero-dep), `LocalEmbedder` (fastembed/ONNX, bge-base),
+  `OpenAIEmbedder`, and `DiskCachedEmbedder` (persistent SQLite cache keyed by model + dim + text).
+  `LocalReranker` (cross-encoder, length-capped to avoid ONNX crashes).
+- **Stores** — `InMemoryStore` with a vectorised cosine scan over a **cached** embedding matrix
+  (numpy; comfortable to ~1M memories) and an identical pure-Python fallback; `SQLiteStore` for
+  **persistence across restarts** with **no native extension** (pure stdlib sqlite3).
+- **float32 in-memory embeddings** — records store the embedding as a float32 numpy array, not a
+  Python `list[float]` (~32 B/value). Measured ~**7× smaller footprint** at 768 dims (a 1M-record
+  in-memory store drops from ~24 GB to ~3.5 GB) and **faster queries** (float32 matmul); SQLite already
+  persisted float32. Measured by `eval/bench_perf.py` (latency / throughput / real tracemalloc footprint
+  — the numbers the project had never measured).
+- **Hybrid retrieval** (BM25 fused with semantic) — off by default; see `BENCHMARKS.md` for the
+  honest negative result on conversational data.
+- **Belief revision** (supersession) for typed durable facts — off by default; chat never supersedes
+  chat. Paraphrased updates are caught by the embedder's cosine similarity (no hand-tuned synonym map),
+  so it generalizes beyond any one dataset.
+- **Local NLI** (`midas/nli.py`, LLM-free) — a small int8 ONNX MNLI cross-encoder (onnxruntime +
+  tokenizers, ~70 MB, no torch/API). Powers **contradiction-gated conversational belief revision**:
+  a chat turn revises an earlier belief only when NLI scores it an actual contradiction. This *fixes*
+  the cue-heuristic's over-supersession (LongMemEval temporal recall restored 0.76 → **0.95**) while
+  staying precise on real updates — closing the "cheap no-LLM contradiction detection" open problem.
+  Also exposes **post-hoc answer-grounding** (`--answer-verify-nli`) — override to "I don't know" when
+  no retrieved turn entails the answer. Honest result: it does NOT reliably improve abstention (a
+  deterministic-reader A/B is unchanged, 0.37→0.37) because the confabulation is drawn from a retrieved
+  distractor that *entails* it. Abstention/Calibrated remains the open frontier; see docs.
+- **Entity-grounded abstention** (`midas/entity.py`, LLM-free) — a new abstention lever orthogonal to
+  cosine/NLI: abstain when the answer's source turn is about a *different entity* than the question asks
+  (the diagnosed confab-from-distractor root cause). Dropping recurring *attribute* words makes the focus
+  the entity noun; **offline-validated 8/8** on the diagnosed failure cases (incl. "favorite colour" vs
+  "favorite food", "city" vs "Barcelona"), 11 tests. Honest limit: crafted cases — the end-to-end win
+  needs a capable reader (local 1B doesn't confabulate-from-distractor; hosted credits exhausted).
+- **Time-aware retrieval** (LLM-free) — memories carry real **event time** (`remember(created_at=…)`);
+  `recall`/`build_context` take a query `now` so recency decays from when a question is asked, context
+  renders true dates (UTC), and a "today" header anchors relative-time reasoning. Bitemporal signal,
+  no LLM. Eval ablation: `--midas-no-time`.
+- **Selective forgetting + temporal tiers** (LLM-free) — `Memory.forget_decayed()` evicts the
+  lowest-value memories (`memory_value` = importance × recency) to bound storage and context growth,
+  **protecting the durable tier** (facts/preferences/constraints, high importance) and never orphaning
+  a supersession chain; returns the forgotten ids (deletion audit trail). `Memory.tier()` names a
+  memory's horizon — short (≤1d) / medium (≤1w) / long (multi-day). Measured with `eval/retention.py`
+  (eviction policies at the same retained budget): on data with an importance signal, value-based
+  forgetting **holds recall@k 1.00 at 25–50% retention** while recency/random eviction fall to
+  0.17–0.60; on uniform-importance chat it **reduces to recency** (honest — needs a per-turn importance
+  signal, the next step) while cutting context tokens ~3×. Purely additive: no-forget recall@k
+  unchanged (LoCoMo 0.62).
+- **Content importance scoring** (`ContentImportance`, LLM-free) — derive a turn's importance 1–5 from
+  content alone (content-word density, numbers/dates, proper nouns, anti-backchannel); `Memory(
+  importance_scorer=…)` auto-applies it to turns ingested without one, so raw chat gets a salience for
+  forgetting/tiering. Measured: as a forgetting **protection** it lifts LoCoMo recall@k under eviction
+  from 0.10 (recency) to **0.18** (sheds filler, keeps facts); as a pure rank it helps only at moderate
+  compression.
+- **Novelty-vs-store importance** (`Memory(novelty_weight=…)`, LLM-free) — blends importance with
+  `1 − max-cosine-to-store` so a *new* fact can outrank a *repeated* one. **Off by default: a measured
+  negative.** At equal budget it is neutral on LoCoMo/synthetic recall@k and *harmful* on multiday
+  (1.00 → 0.60), because repetition usually signals importance and demoting restated gold evicts it.
+  Kept as a tested, opt-in knob; its right home is consolidation (dedup), not eviction-ranking.
+- **Reinforcement importance** (`Memory(reinforce=True)`, LLM-free) — the inverse of novelty: a restated
+  turn *boosts* the matched memory's importance + recency (repetition ⇒ salience); in `capture` a
+  restatement reinforces the existing memory and is skipped. **Off by default: also a measured negative**
+  — recall@k drops at equal budget (LoCoMo 0.08→0.03 @25%; multiday 0.60→0.40 @25%). Unifying finding:
+  on raw conversation **repetition tracks commonness, not importance**, so neither novelty nor
+  reinforcement improves no-LLM forgetting. Content-salience as a *protection* stays the best signal.
+- **Extractive consolidation** (`Memory.consolidate`, LLM-free) — collapse near-**duplicate** restatements
+  to the single highest-value copy (cosine ≥ threshold, chains preserved); extractive (drops redundant
+  records, keeps provenance — never LLM-rewrites). Measured safe (recall@k held: LoCoMo 0.27→0.26 dropping
+  10 dups at 0.92); yield is modest at safe thresholds on paraphrase-heavy data and grows with literal
+  redundancy/scale.
+- **MCP server** (`python -m midas.mcp_server`) — `remember` (auto-derives importance from content),
+  `recall` (source-traceable), `build_context`, `maintain` (no-LLM retention: dedup + selective
+  forgetting, returns the **deletion audit** of removed ids), `stats` (counts + temporal-tier
+  distribution), `forget`, `forget_all`. Optional SQLite persistence via `MIDAS_MCP_DB`; optional
+  **bounded memory** via `MIDAS_MCP_MAX_RECORDS` (auto-forget the lowest-value tail over the cap). The
+  privacy/cost/provenance/retention surface for long-running and enterprise agents.
+- **Zero-config auto-memory** (LLM-free) — install the MCP server and Midas starts remembering on its
+  own. The server **injects a memory policy** into the agent (MCP `instructions` + a `memory_session`
+  prompt): recall-then-`capture`. `Memory.capture()` + `MemoryPolicy` impose the relevance parameters —
+  it scores each turn's importance, enforces a floor (`MIDAS_MCP_MIN_IMPORTANCE`, default 2) and skips
+  duplicates, and reports stored/skipped + why. The agent captures freely; Midas decides what's kept.
+- **Eval harness** (`eval/`, dev-only) — LoCoMo + LongMemEval loaders, deterministic `recall@k`,
+  per-adapter cost/latency instrumentation, and an optional LLM judge (hosted or local Ollama,
+  seed-pinned + serialized for reproducibility). **Reader and judge models are decoupled**
+  (`--reader-model` vs `--judge-model`) so correctness can be measured with a fixed judge while
+  sweeping readers — the apples-to-apples protocol published leaderboards use (e.g. gpt-4o judge).
+- **Artifacts** — `BENCHMARKS.md` (reader-independent results + reproduce commands),
+  `docs/research-notes.md` (measured findings), a coding-agent demo, PEP 561 typing (`py.typed`),
+  and an MIT license.
+
+### Measured (see BENCHMARKS.md)
+- Retrieval `recall@k`: LongMemEval-`s` **0.95** (n=40, time-aware) and LoCoMo **0.85** (5
+  conversations) vs a recency-window baseline ≤0.03. Time-awareness lifts **temporal recall@k
+  0.86→0.95** (deterministic A/B, `--midas-no-time`), no real regression elsewhere.
+- Answer correctness (reader = gpt-4.1-mini, n=40): Midas **0.82** vs baseline **0.05**. Per-category
+  answer deltas are within run-to-run judge noise at n≤13, so we lead with `recall@k`.
+- **Same-reader head-to-head (judge=gpt-4o, structured answerer):** Midas **0.84 @ gpt-4o = SOTA
+  Observational Memory's 0.84**, with **zero LLM at ingest** (OM runs an LLM per conversation);
+  0.87–0.89 @ gpt-5-mini vs OM 0.95. Midas leads multi-session (0.89 vs 0.872).
+- Structured answerer (extract relevant dated entries + compute time deltas before answering) lifts
+  non-reasoning readers (gpt-4o 0.76→0.84) and is neutral for reasoning readers.
+- Ingest cost: **0 LLM calls, $0 API, 0 data egress** (local embeddings only).
+- In-memory recall latency ~0.2 µs/record after matrix caching (~70× the naive Python scan).
+
+### Notes
+- Reader-independent metrics (`recall@k`, cost) are primary; end-to-end answer correctness is
+  reader-dominated and reported as secondary/noisy — see `docs/research-notes.md`.

midas_memory-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to Midas
+
+Thanks for considering a contribution. Midas is **eval-first**: the project's one durable asset is that
+its reported numbers are true. A few principles keep it that way.
+
+1. **Measure, don't claim.** Any change that affects retrieval or forgetting must show its effect on a
+   reproducible metric — `recall@k` is deterministic (`python -m eval.runner …` / `python -m
+   eval.retention …`). Quote numbers with the command, dataset, `n`, and caveats.
+2. **Regression-check.** Run the suite (`python -m pytest -q`); for retrieval changes, confirm LoCoMo
+   `recall@k` is unchanged. A win on a toy can break real data — that has happened here before.
+3. **No LLM at ingest or query.** The wedge is local, cheap, auditable. New *no-LLM* mechanisms are very
+   welcome; an LLM in the ingest/query path is not.
+4. **Honest negatives are valued.** A measured "this didn't work" is a real contribution — the design
+   doc (`docs/long-horizon-memory.md`) keeps several on purpose.
+
+## Dev setup
+
+```bash
+git clone https://github.com/vornicx/Midas && cd Midas
+pip install -e ".[all,dev]"
+python -m pytest -q
+```
+
+Open an issue first for anything non-trivial. Small, measured, well-tested PRs merge fastest.

midas_memory-0.0.1/LICENSE

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