{"slug": "show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db", "title": "Show HN: Offline project memory for coding agents – no API key, no vector DB", "summary": "A developer released Adaptive Agent Memory Research (AAMR), an offline, dependency-free memory system for coding agents that stores project memory in a single append-only memory/events.jsonl file with no API key, vector database, daemon or cloud account required. The system installs via git clone and an MCP registration command that exposes eight tools — memory_status, memory_search, memory_context, memory_get, memory_timeline, memory_add, memory_supersede and memory_rebuild_index — and ranks what to retain by measured future usefulness rather than semantic similarity; the author states it is a research engine, not a finished product, and that of 74 registered experiments 39 are completed or retracted, 20 blocked, 7 invalidated or partly valid and 8 awaiting execution, with none independently reviewed.", "body_md": "A local-first, model-agnostic memory system that decides what to keep from\n\n**the measured future usefulness of past experience** — not from what looks similar to your query.\n\nThe memory engine this research is built on is dependency-free, offline, and works today on **your** project. Point any MCP client at it:\n\n```\ngit clone https://github.com/krapcys1-maker/adaptive-agent-memory-research ~/aamr\nclaude mcp add project-memory -- python ~/aamr/tools/project_memory/server.py --root .\n```\n\nYour agent now has eight tools — `memory_status`, `memory_search`, `memory_context`, `memory_get`, `memory_timeline`, `memory_add`, `memory_supersede`, `memory_rebuild_index` — writing to a single append-only `memory/events.jsonl` in your repository. No API key, no vector database, no daemon, no cloud account, no `pip install`.\n\nPrefer no MCP client? Everything works from the CLI. Run it from your own project with `--root .`; without `--root` the CLI reads and writes this repository's own research log:\n\n```\npython ~/aamr/tools/project_memory/cli.py --root . add --kind decision \\\n  --title \"Use SQLite for the cache\" \\\n  --summary \"Chose SQLite over Redis because the deployment target has no daemon.\" \\\n  --source docs/adr/0003.md\npython ~/aamr/tools/project_memory/cli.py --root . search \"why sqlite\"\n```\n\n**This is the research engine, not a finished product.** It is used daily by this project on itself, which is the strongest thing we can honestly say about it. Bugs, rough edges, and honest reports of both are welcome — if setup fights you, [open an issue](https://github.com/krapcys1-maker/adaptive-agent-memory-research/issues/new/choose) and say so.\n\nAn agent's context window is a workspace, not a memory. Once a conversation is compacted, whatever was dropped is gone — including the thing that turns out to matter three weeks later.\n\nThe usual answer is to embed everything and retrieve by similarity. That answers *what looks like this query*, which is not the same question as *what will this agent need*. Those two come apart badly, and this project exists to measure exactly where.\n\nTwo stores, not one. A fast, evidence-preserving episodic log that learns from single experiences, and a slower semantic or procedural store that consolidates what recurs. What moves between them is governed by **measured future utility** rather than by semantic similarity or retrieval frequency.\n\n```\n                 experience\n                     │\n                     ▼\n        ┌────────────────────────┐\n        │   append-only log      │   immutable evidence, never rewritten\n        └────────────┬───────────┘\n                     ▼\n        ┌────────────────────────┐\n        │   memory controller    │   write · preserve · consolidate · revise · archive\n        └────────────┬───────────┘\n                     ▼\n    ┌──────────┬───────────┬────────────┬──────────┐\n    │ episodic │ semantic  │ procedural │ failure  │\n    └──────────┴─────┬─────┴────────────┴──────────┘\n                     ▼\n        ┌────────────────────────┐\n        │  measured future use   │   ◄── the part that is actually research\n        └────────────┬───────────┘\n                     ▼\n                 retrieval ──────────► agent\n```\n\nThe append-only log, the controller and retrieval are built and running — that is what the two-minute setup above gives you. The box marked *the part that is actually research* is the open question, and the four stores below the controller are a design rather than a measured decomposition. This diagram is the hypothesis, not a claim about what works.\n\nOf 74 registered experiments, 39 are completed or retracted, 20 are blocked (waiting on a corpus, four of them also on independent review), 7 were invalidated or only partly valid, and 8 are designs or review packets awaiting execution; `python scripts/registry_summary.py` prints the current counts. All are exploratory and none is independently reviewed, so read these as measurements rather than settled science — but they are measurements, and the data is in the repository.\n\n**A superseded fact is maximally similar to the fact that replaced it.** Mean cosine 0.816 between an old fact and its replacement, against a corpus baseline of 0.372 — two pairs at 1.000. With the metadata filter removed, the stale version was the nearest neighbour in 6 of 9 cases and its median rank was 1. *Content cannot separate a retired fact from its successor. Only bookkeeping can.* → `PMLAB-STALE-E1`\n\n**One timestamp cannot answer \"what did we believe at time T\".** It scored 0.00 on that question and leaked future information into 6 of 18 queries. Separating valid time from transaction time scored 0.944 with zero leaks. The caveat matters as much as the result: every design scored 1.00 on *what is true now*, so the second axis buys nothing unless historical questions get asked. → `PMLAB-REV-V0`\n\n**A 220 MB local multilingual embedder lifted Polish-query recall@10 from 0.156 to 0.978** — but a hand-built glossary already reached 0.867, and the queries are translated memory titles looked up against their own ids, not questions. Safety was not measured in this run; a separate, smaller one (`PMLAB-REUSE-CHAR-001`) found 0.200 forbidden intrusion for dense retrieval against 0.050 for lexical search. → `PMLAB-XLANG-E2`\n\n**An association graph over memory lowered Recall@5 by 0.114** on the mechanical-gold stratum (95% CI −0.179 to −0.054); at Recall@10 the difference there is −0.039 and its interval includes zero, while the smaller authored-gold stratum points the same way (−0.052 at @5, −0.056 at @10). The earlier, favourable version of this result was **retracted by us**: its leakage control removed one edge where it needed to remove several, so the gold-generating group reassembled over two hops. → `PMLAB-ASSOC-E2` retracted, `PMLAB-ASSOC-E3`\n\n**An early baseline suggested that perfect recall can sit beside a wrong top-ranked line — that result did not survive a corpus repair.** The committed baseline reports **1.000 recall@10** for the poisoned-instruction family and the poisoned line ranked *above* the genuine rule in **25%** of probes (3 of 12). Re-running the same, unchanged script on the current corpus gives 0 of 12 for that family (recall@10 still 1.000) and an overall recall@10 of 0.881 against the committed 0.810. The cause is a corpus repair made 34 minutes after the baseline was written (commit `cd5c3f4`): before it, the 84 probes asked only 24 distinct questions (the 12 poisoned-instruction probes asked 4), so many probes did not identify their own case. The script run on a snapshot of the earlier corpus reproduces the committed baseline byte for byte, and on a snapshot of the repaired corpus it reproduces the re-run. Both are recorded next to the original, which is left untouched, in [`data/lab/corpus-h1/baseline-v0.1-rerun-2026-11-01/`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/data/lab/corpus-h1/baseline-v0.1-rerun-2026-11-01/README.md). Treat the 25% as an artefact of probes that did not identify their own case, not as a finding about retrieval or memory systems. → `PMLAB-H1-BASE-E1`\n\n**We cannot currently instantiate tier I3 of our own independence ladder.** Two roles of one model fabricated an evidence identifier zero times across 120 queries, so the error correlation is *undefined* rather than zero — and the harness reports undefined, because 0.0 would claim an independence nobody measured. → `PMLAB-DECORR-E1`\n\nFour of those six are negatives and one is a retraction of our own work. **That ratio is the honest one at this stage**, and it is the thing this project is most willing to defend.\n\nThere is no headline benchmark table on this page, and there will not be one until it is earned. The comparison that matters — adaptive memory against native compaction and against vector retrieval, at a fixed context budget, on a long history — needs a corpus and a reader model.\n\nThe corpus now exists: [corpus H1](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/data/lab/corpus-h1/README.md), 538 events over 30 simulated days, 84 delayed probes across seven failure families, generated deterministically with no model and no API key. Its first run found a defect *in the corpus* — document length predicted the answer in 12 of 12 instances of three families — which is exactly what the construction-test tier is for. Both the broken and the repaired measurement are published.\n\nWhat is still missing is the reader model that scores whether an arm could answer from what it retained, and the compaction arms themselves. That is [#41](https://github.com/krapcys1-maker/adaptive-agent-memory-research/issues/41), still open, still the highest-leverage task.\n\nWe have pre-committed to publishing that result whichever way it falls. Given that three separate runs here have already measured our own mechanisms *harming* retrieval, a negative headline is a live possibility — and it would be published in the same font as a positive one.\n\n```\ngit clone https://github.com/krapcys1-maker/adaptive-agent-memory-research\ncd adaptive-agent-memory-research\npython -m pip install -r requirements-dev.txt\n```\n\nThe install pulls about 230 MB, mostly `transformers`, which is needed only to import one frozen audit script; the memory engine itself needs nothing.\n\nInspect the memory this project keeps about its own research, and watch it assemble a context bundle under a hard character budget:\n\n```\npython tools/project_memory/cli.py status\npython tools/project_memory/cli.py context \"what is blocking independent review\" --char-budget 4000\n```\n\nCheck that the append-only log satisfies every invariant decidable from its bytes — no model, no network, no reviewer:\n\n```\npython scripts/verify_memory_integrity.py\n```\n\nAudit the whole repository for claims that no longer hold:\n\n```\npython scripts/audit_repository_claims.py\n```\n\nThat last one lists what no longer holds. It fails only on a critical finding: a declared hash that matches neither the working copy nor the Git blob, meaning a frozen artifact changed after it was frozen. It currently reports none. One declaration that did drift (`scripts/corpus/address_extract.py`, edited two minutes after the E2-A2 freeze) is shown as a low `explained-drift` finding, backed by a note next to the manifest that the audit re-derives from Git, because this project does not rewrite a freeze to make an audit pass. The medium findings — registry rows pointing at artifacts for experiments that have not run, experiment identifiers described in documentation but absent from the registry, memory sources that are not tracked — are printed, not hidden. Run it to see the current counts; they change as work lands.\n\nContributions run at three depths, and **you do not need a background in memory research for the first one.**\n\nIssues labelled [`good first issue`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/labels/good%20first%20issue) and [`no-expertise-needed`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/labels/no-expertise-needed) are ordinary software work: a scoped bug, a missing exclusion rule, a CLI subcommand, reading one unfamiliar repository carefully. Each states what \"done\" means before you start.\n\nIf the setup instructions above fail on your machine, saying so in an issue is itself a useful contribution — this is developed on Windows and tested on Linux, and that gap has already produced one real defect.\n\n**A negative result closes an issue here.** If you inspect something and find it is not what we assumed, write that down and you are done. Several of the findings above are exactly that.\n\nIssues labelled [`track:engine`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/labels/track%3Aengine) build the machinery the research needs: sealed held-out splits, error-decorrelation measurement, the bitemporal query layer, cost-normalised retrieval metrics. These need care but not domain expertise.\n\n**Finding a hole in our method is worth more than completing a task.** The sealed-split tool carries three guards, each added after the corresponding attack was reproduced against it. A fourth would be the better contribution.\n\nIssues labelled [`independent-review`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/labels/independent-review) need someone who can judge evidence. Read [the independence ladder](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/independence-ladder.md) first — it explains why a large share of what once required an expert reviewer is now a mechanical check, and what genuinely still needs human judgement.\n\nEverything goes through [CONTRIBUTING.md](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/CONTRIBUTING.md). Disagreement with a recorded conclusion is welcome; that is what the evidence ledger is for. Say hello in [Discussions](https://github.com/krapcys1-maker/adaptive-agent-memory-research/discussions).\n\n- User data stays local by default.\n- The system must be model-agnostic.\n- Raw evidence is append-only during early research.\n- Experimental forgetting must never destroy the only copy of a memory.\n- Every derived memory preserves provenance.\n- Facts, hypotheses, decisions, preferences, and instructions are never conflated.\n- A retrieved memory is not automatically a useful memory.\n- Every added mechanism justifies itself in controlled evaluation.\n\nTwo 2026 systems were verified in August 2026 and both occupy ground this page had been treating as open.\n\n[APEX-MEM](https://arxiv.org/abs/2604.14362) (ACL 2026, Amazon) implements entity-property-value triplets over an append-only store with query-time temporal resolution — the architecture this project converged on independently — at 88.88% LoCoMo and 86.2% LongMemEval. **Structured temporal memory is not a novel claim here and is not made as one.**\n\n[Fidelity Before Structure: Verbatim Chunks Beat Lossy Artifact Extraction in Long-Conversation LLM Memory](https://arxiv.org/abs/2601.00821) (formerly \"Verbatim Chunks Beat Extracted Artifacts\"; v4, July 2026) finds extraction *losing* to raw chunks by 15.9 points on LoCoMo, and attributes 78.8% of the 3,121 missing keywords in failed questions to extraction gaps. This project measured 85.7% abstention from a deterministic extractor — a different quantity on a different corpus, but consistent with that finding and a reason to take the paper's conclusion seriously rather than route around it.\n\n[A-MAC](https://arxiv.org/abs/2603.04549) (March 2026) is verified: it scores memory admission with five factors, one of them an LLM-estimated *future utility*, so future utility as a retention criterion is already occupied as a predicted score. Whether it can be *measured causally* (question 3 below) is not addressed in its abstract and stays open. NEMORI and the other systems listed in [#48](https://github.com/krapcys1-maker/adaptive-agent-memory-research/issues/48) are still being verified; until that resolves, read question 3 as **open only in its causal form**.\n\nWhat still looks unoccupied is not a system but a diagnostic programme: *when and why similarity stops being the right access mechanism*, measured through failure attribution, an oracle router ceiling, near-clone density and context cost. Full assessment in [related work and novelty](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/related-work-and-novelty.md), including the process failure that let this be found late.\n\nDoes an agent need complementary memory systems — an evidence-preserving episodic store for rapid learning from single experiences, and a slower semantic or procedural store that consolidates recurring evidence? And should transitions between them be governed by **measured future utility** rather than by semantic similarity?\n\n1. What is the atomic unit of agent memory: message, event, fact, relation, episode, procedure, or decision?\n2. How can storage failure be distinguished from retrieval failure and from reasoning failure?\n3. How can future utility be measured causally rather than inferred from retrieval frequency?\n4. When should exact episodes be consolidated into semantic or procedural knowledge?\n5. How can memories be updated without losing provenance, uncertainty, or superseded historical states?\n\nEvidence collection alongside gated laboratory testing. Each falsifiable hypothesis may enter an exploratory test under the [research-to-experiment gate](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/11-research-laboratory/research-to-experiment-gate.md); confirmatory claims, added architecture, and any product implementation remain blocked behind stricter benchmark, reproduction, safety, and review gates.\n\nWork runs in three tracks — engine, experiment, community — with milestones **M1 Engine**, **M2 Execute**, **M3 Independence**. New preregistrations are paused until the existing unexecuted drafts are triaged, because the project was designing protocols faster than it could run them.\n\nBoth defects this section used to list as open are now closed, and how they closed is more interesting than that they did. Frozen hashes were reproducible only on a Windows checkout because Git's end-of-line conversion made 843 of 1348 files under `data/` differ byte for byte across platforms; `.gitattributes` now disables conversion repository-wide. Six frozen artifacts had been modified after freezing, by two distinct causes rather than one. CI verifies freezes on Linux with full history, so the check cannot pass vacuously.\n\n## **Deep research — the full repository**\n\nNew contributors do not need all of this. Read the first three, then follow whatever your issue touches.\n\n1. [Start here](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/START_HERE.md) — the shape of the problem\n2. [Operating doctrine](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/operating-doctrine.md) — what we test next, and why that one\n3. [Bootstrapping strategy](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/bootstrapping-strategy.md) — why the tool is also the corpus, and what that costs\n4. [Independence ladder](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/independence-ladder.md) — how a claim earns promotion\n5. [Repository map](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/REPOSITORY_MAP.md) — where everything lives\n6. [Scope](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/scope.md) and[definitions](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/definitions.md)\n7. [Research plan](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/RESEARCH_PLAN.md) and[research questions](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/00-project/research-questions.md)\n8. [Human memory](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/01-human-memory/README.md) ·[LLM memory](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/02-llm-memory/README.md) ·[mapping between them](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/03-human-ai-bridge/mapping.md)\n9. [Systems catalog](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/04-systems/catalog.md) ·[benchmark catalog](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/05-benchmarks/catalog.md)\n10. [Research laboratory](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/11-research-laboratory/README.md) and the[experiment gate](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/docs/11-research-laboratory/research-to-experiment-gate.md)\n\n```\ndocs/00-project/          Scope, definitions, methodology, independence ladder, decisions\ndocs/01-human-memory/     Cognitive psychology and neuroscience\ndocs/02-llm-memory/       LLM and agent memory mechanisms\ndocs/03-human-ai-bridge/  Testable mappings and invalid analogies\ndocs/04-systems/          Open-source systems and architecture comparisons\ndocs/05-benchmarks/       Benchmark coverage, flaws, and evaluation design\ndocs/06-datasets/         Training and evaluation data\ndocs/07-literature/       Reading queues, bibliography, evidence ledger\ndocs/08-experiments/      Experiment specifications\ndocs/09-synthesis/        Findings, open questions, exclusions\ndocs/10-comparative-biological-memory/  Animal, motor, immune, cellular, collective memory\ndocs/11-research-laboratory/            Protocols, benchmark ladder, gates, architecture boundary\ndocs/12-interdisciplinary-memory/       Compression, storage, control, offloading synthesis\ndocs/13-brain-ai-transfer/              Brain-to-AI mechanism atlas and transfer gaps\ndata/catalogs/            Machine-readable paper and repository catalogs\ndata/lab/                 Experiment registry, corpora, frozen runs, results\nscripts/                  Experiment runners, audits, discovery helpers\ntests/                    Test suite; runs on every pull request\nmemory/                   Append-only project memory and its generated index\ntools/project_memory/     Dependency-free CLI and MCP memory adapter\n```\n\nRepository content is written in English so contributors can collaborate internationally. Issues and discussions may use any language; durable findings are summarised in English.\n\n- Code (`tools/` ,`scripts/` ,`tests/` ,`.github/workflows/` ):[Apache-2.0](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/LICENSE) .\n- Documentation, research notes and the experiment data produced here (`docs/` ,`data/` ,`memory/` ):[CC BY 4.0](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/LICENSES/CC-BY-4.0.txt) .\n- `data/lab/arena/*/vendor-patch/` holds modified copies of Mem0 1.0.6 (Apache-2.0); see[NOTICE](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/NOTICE) .\n- LongMemEval (MIT) is quoted in arena result files; LoCoMo (CC BY-NC 4.0) is not redistributed. Other systems, datasets and papers keep their own licences.\n- Contributions are accepted under the licence of the path they touch (inbound = outbound). The path map is [`REUSE.toml`](https://github.com/krapcys1-maker/adaptive-agent-memory-research/blob/main/REUSE.toml) .", "url": "https://wpnews.pro/news/show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db", "canonical_source": "https://github.com/krapcys1-maker/adaptive-agent-memory-research", "published_at": "2026-11-01 17:57:27+00:00", "updated_at": "2026-11-01 18:21:24.124820+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols", "ai-research"], "entities": ["Adaptive Agent Memory Research", "krapcys1-maker", "Model Context Protocol", "Claude", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db", "markdown": "https://wpnews.pro/news/show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db.md", "text": "https://wpnews.pro/news/show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db.txt", "jsonld": "https://wpnews.pro/news/show-hn-offline-project-memory-for-coding-agents-no-api-key-no-vector-db.jsonld"}}