{"slug": "show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log", "title": "Show HN: NexusMem – local memory for coding agents, not just Git log", "summary": "NexusMem, a local memory tool for coding agents, records shell commands, git history, and project docs into a SQLite database, serving ranked, token-budgeted slices on demand. The tool, requiring Node 22 or newer and git, uses BM25 and vector search fused with Reciprocal Rank Fusion, and keeps all data on disk with no cloud or telemetry. In a two-day test on its own repository, NexusMem indexed 527 nodes, including 321 shell commands and 16 git commits, capturing information that git log alone cannot provide.", "body_md": "Your coding agent can read `git log`\n\n. It cannot read the four things you tried last Tuesday that\ndidn't work.\n\nNexusMem records what actually happened on your machine (shell commands and their exit codes, git history down to the patch of each changed file, project docs, optionally your assistant transcripts) into a local SQLite database, and serves back a ranked, token-budgeted slice of it on demand. Everything stays on disk. No account, no cloud, no telemetry.\n\nThe shell history is the part worth caring about. Git tells an agent what shipped. Shell history tells it what was attempted, in what order, and which commands exited non-zero. That information exists nowhere else, and it disappears when your terminal scrollback rolls over.\n\nFrom inside any git repository:\n\n```\nnpx nexusmem init\nnpx nexusmem sync\n```\n\nThen ask it something. Real output from this repository, top 2 of 5 hits:\n\n``` bash\n$ nexusmem query \"windows spawn failure\"\n\nRelevant history for: windows spawn failure\n\n- 2026-08-09 fix: distinguish a failed git spawn from \"not a git repository\"\n  readRepoInfo collapsed three unrelated failures into one error: git running and reporting\n  the path is not a work tree, git not being installed, and the process failing to spawn at\n  all. Dogfooding hit the third case in two separate sessions...\n- 2026-08-09 README.md — Before a tagged release\n  - [ ] Retry on transient process-spawn failures on Windows\n```\n\nA commit and a docs section, ranked against each other, inside whatever token budget you gave it. Nothing was summarized by a model on the way out; the ranker just decided what not to send. (One optional source, session summaries, does run a local model — but at ingest time, never on the way out. What you query is always stored text.)\n\nFor a sense of what actually accumulates, here is `nexusmem status`\n\non this repo after two days:\n\n```\n527 node(s)  2026-08-08 .. 2026-08-09\n       321  shell_command\n       130  conversation_turn\n        60  doc_section\n        16  git_commit\n```\n\nSixteen commits. Three hundred and twenty-one shell commands. The commits were already retrievable by any agent with a terminal. The rest was not.\n\nThat `conversation_turn`\n\nrow only appears because this corpus was synced with `--conversation`\n\n.\nAssistant transcripts are the one source that is off by default and stays off until you opt in, since\nthey are the likeliest place for a pasted credential to be sitting. A default install indexes git\ncommits, their diffs, shell and docs.\n\nRequirements: Node 22 or newer, and git. Node 20 will not work, because `better-sqlite3`\n\nships no\nprebuilt binary for it and Node 20 went end-of-life in April 2026. Ollama is optional and only\naffects semantic search (see below).\n\nEvery source normalizes to the same `MemoryNode`\n\nshape, so a commit, a shell command and a docs\nsection compete on equal terms. Retrieval runs BM25 over FTS5 and, if an embedding model is\nreachable, a vector search over `sqlite-vec`\n\n, then fuses the two with Reciprocal Rank Fusion.\n\nRRF fuses on rank *position* only, never on raw scores. That is the entire reason it is safe here: a\nBM25 cost and a vector distance live on unrelated, unbounded scales, and position is the only thing\nthey agree on. No hand-tuned normalization constant sits between them.\n\nRanking then multiplies three factors:\n\n```\nscore = relevance × signal^0.215 × recency^0.288\n```\n\n`relevance`\n\ncomes from the query. `signal`\n\n(a `fix:`\n\ncommit outranks a `chore:`\n\n; a command that\nexited non-zero outranks one that succeeded) and `recency`\n\nare priors that hold before any query\nexists. Each factor is floored into `[floor, 1]`\n\nrather than `[0, 1]`\n\n, so one weak dimension cannot\nzero out a strong match.\n\nThose exponents are derived, not tuned. Priors kept overturning the query: on one real query a `fix:`\n\ncommit took rank 1 from a better-matching docs section on a 44% signal edge against a 15% relevance\ndeficit. So the priors get a **shared** budget — across their whole range they may overturn at most a\n2× relevance gap — split evenly between them, and each is raised to the power that makes its own span\nworth exactly its share (`span^exponent = √2`\n\n). Priors still order equally-relevant hits exactly as\nbefore, since the transform is monotonic. They just cannot outvote the question anymore.\n\nThe budget is shared rather than per-prior for a reason found by dogfooding, not by reading the\narithmetic: the score *multiplies* the priors, so capping each at 2× separately left the pair free to\noverturn 4×. That describes every commit made during an active working day — fresh and high-signal at\nonce — so the failure landed on precisely the days with the most worth remembering. A query about the\nPowerShell hook returned two unrelated same-day `fix:`\n\ncommits at ranks 3 and 4 while the section that\nanswered it sat at rank 6. Adding a third prior now re-divides the same budget instead of enlarging it.\n\nWithout Ollama, vector search is skipped and you get BM25 only. That path is fully supported, not a\ndegraded error state; `sync`\n\nand `query`\n\nboth succeed and simply do less.\n\nWith `sources.session.enabled`\n\n, each finished session becomes one distilled node next to the raw\nexchanges — what was decided and why, rather than forty individual turns. It runs a local Ollama\nchat model (`qwen2.5:3b`\n\nby default); nothing is downloaded automatically and nothing leaves the\nmachine.\n\n```\nnexusmem scan-session --dry-run\n```\n\nThat prints the exact prompt a session would produce, after redaction and budget trimming, without calling the model.\n\nThree things bound the cost. A session is only summarized once it has been quiet for\n`settleMinutes`\n\n(default 30), so a session in progress is not re-summarized on every sync. The\nprompt is hashed, and an unchanged hash skips the model entirely — on this repo a steady-state sync\nof 14 summarized sessions takes 0.25s and makes no model calls. And `maxSessions`\n\n(default 10) caps\nhow many reach the model per run; the rest are reported as queued and picked up next sync.\n\n**What it is actually like, measured on 14 real sessions with qwen2.5:3b.** The summaries\nthemselves are good: decisions with their reasons, in the shape the prompt asks for. Titles are less\nreliable — the model returned a usable one about a third of the time, and otherwise produced a\nconversational preamble, a stray bullet, or a bare \"Summary of the Session\". Those are rejected and\nthe title falls back to the first line of the question that opened the session, which is always\nspecific even when it is not elegant. Compliance was worst on long sessions and on transcripts not\nin English. A larger model (\n\n`qwen2.5:7b`\n\n) is the lever if the titles matter to you; set\n`sources.session.model`\n\n.\n\n```\n{\n  \"mcpServers\": {\n    \"nexusmem\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"nexusmem\", \"mcp\"]\n    }\n  }\n}\n```\n\nThree tools over stdio: `search_memory`\n\nreturns the packed context block, `sync_project`\n\ningests, and\n`get_status`\n\nreports what is currently remembered. Each takes an explicit `projectRoot`\n\n, because an\nMCP tool call carries no shell working directory. `sync_project`\n\nruns `init`\n\nfor you if the\nrepository has not been set up.\n\nScraped history files (PSReadLine, `.bash_history`\n\n, `.zsh_history`\n\n) give you command text and not\nmuch else. The hook gives you working directory, exit code and a real timestamp:\n\n```\nnexusmem hook install\n```\n\nIt wraps your existing PowerShell prompt rather than replacing it, is idempotent, and\n`nexusmem hook remove`\n\nundoes it cleanly.\n\nExit codes are what make this worth installing. A failed command is a stronger signal than a successful one, and without the hook there is no way to tell them apart.\n\nTwo numbers get conflated in tools like this, so they are kept apart here.\n\n**Packer efficiency** is how much the ranker trims from its own candidate set. On this repository's\ncorpus it runs 81–84%. It is useful for tuning the ranker and useless as a claim about your bill,\nbecause the baseline is hypothetical: without NexusMem those candidates were never going into your\ncontext window in the first place.\n\n**End-to-end saving** compares packed context against reading the equivalent files in full. Measured\nat **~40%** on design queries against this codebase, hand-tallied from one real session rather than\ninstrumented. Treat it as an order of magnitude.\n\nThe long-term target is >70%, and this repository cannot demonstrate it. That figure describes repos with thousands of commits, where the win comes from omitting hundreds of unrelated items rather than shaving a handful. A benchmark at that size is still outstanding, and until it exists the honest number is 40%.\n\nOne thing that is not a percentage: shell commands and conversation turns have no cheap `grep`\n\nequivalent. Without something recording them, they are gone, not merely more expensive to find.\n\nLatency on a ~530-node corpus, warm, p50 over 10 runs:\n\n| Operation | |\n|---|---|\n| BM25 retrieval (FTS5) | ~1.1 ms |\nVector KNN (`sqlite-vec` ) |\n~3.2 ms |\n| Fuse, rank, pack | ~0.6 ms |\n| Query embedding (local Ollama) | ~55–77 ms |\nEnd-to-end hybrid |\n~56 ms |\n\nAll the SQLite work totals about 5 ms. The embedding call is the only thing on this path worth optimizing, and it is somebody else's process.\n\n**Shell history without the hook is unscoped.** Scraped history has no directory context, so it is attributed to whichever repository you ran`sync`\n\nfrom. Bounded to a tail window, and an approximation rather than a guarantee.**Japanese and Chinese depend on the vector pass.** FTS5's`unicode61`\n\ntokenizer splits on whitespace, so languages without space boundaries get no useful BM25 recall.**Rebasing strands nodes.** Rewritten history leaves nodes for unreachable commits. They describe real events so they are not wrong, but a targeted prune does not exist yet.`sync --rebuild`\n\nforces a clean re-scan.**Multi-line PowerShell input is read as separate commands.** A function typed across several lines at the prompt is not reconstructed.**Scrape-fallback ids drift** if the history file is trimmed from the front between syncs. Installing the hook fixes this.**Session-summary titles depend on the model following instructions**, and a 3B model often does not. The fallback keeps them specific rather than generic, but see the section above for what to expect.**Changing the embedding model re-embeds everything.** Vectors from two models are not comparable and`nodes_vec`\n\nrecords no per-row provenance, so`sync`\n\ndrops the lot and rebuilds rather than ranking across a mixture. It says so when it happens. Nodes are untouched and BM25 keeps working throughout.**Diff indexing is bounded, and deliberately lossy.** A first sync indexes the patches of the most recent 200 commits (later syncs only walk`cursor..HEAD`\n\n); merge commits contribute none, since their patch exists only in a combined format this parser does not read; and binaries, lockfiles and build output are skipped so a dependency bump cannot bury the corpus. All of it is still recorded as a`git_commit`\n\nnode. A patch longer than`limits.maxBodyChars`\n\nis truncated, so the tail of a very large change is not indexed. The caps live under`sources.diff`\n\nin`config.json`\n\n.**Cross-project recall favours breadth.** Each repository's hits are fused by rank, so a project whose best match is mediocre still contributes a rank-1 item, and rank 1 is worth the same in every list. Adding a repository that has little to say about your question still pushes a few of its results into the budget. Signal, recency and the budget are what hold that in check; there is no per-project quality weight.**The project registry is an index, not a source of truth.** It can point at a database that has moved or been deleted; those are reported and skipped, never silently pruned, because an unmounted drive is not a deleted project.**Conversation chunking is unevaluated.** Splitting long replies at heading boundaries measurably helped, but it has never been tested systematically.**A chunked node's sibling count in one result is capped, not tuned.**`conversation_turn`\n\nand`doc_section`\n\nboth split one reply or file into several nodes; at most 2 of them may appear together in a packed result. Found live: a query for \"token\" returned 9 of its top 12 hits as different pieces of one heavily-sectioned reply, crowding out the node that actually answered it. The cap of 2 is a judgement call, not a measured optimum, same as the ranking priors' budget above.**The size of the prior budget is a judgement call, not a measured optimum.** Priors are now bounded jointly rather than one at a time, which closed a real 4× hole (see the ranking section), but the 2× budget itself has never been tuned against a labelled relevance set — there isn't one. It is a defensible constant, not a result. What is measured is the direction: on four real queries against this repo's own memory, switching to the joint cap moved the section that answered the question up in three of them (the rationale section for \"why BM25 before vector search\" went from rank 4 to rank 1) and displaced no query's correct top hit.\n\n`init`\n\n, `sync`\n\n, `query <text>`\n\n, `status`\n\n, `projects`\n\n, `mcp`\n\n, and `hook install|remove|status`\n\n.\n\nThere are also five dry-run previews (`scan-git`\n\n, `scan-diff`\n\n, `scan-shell`\n\n, `scan-docs`\n\n,\n`scan-conversation`\n\n)\nthat write nothing and print the nodes ingestion *would* create along with their signal scores. That\nis the intended way to tune scoring against a real repository before committing to a change. Add\n`--json`\n\nto pipe them somewhere.\n\nEvery command takes `-C <path>`\n\nto target another repository. On `sync`\n\n, `--conversation`\n\nopts the\ntranscript source in for one run without persisting it, `--no-embed`\n\nskips the vector pass, and\n`--rebuild`\n\ndrops the project's nodes and re-ingests from scratch.\n\n`query --all-projects`\n\nsearches every repository you have run NexusMem in, not just the current one,\nand tags each result with the repository it came from:\n\n``` bash\n$ nexusmem query --all-projects \"why was the retry budget raised\"\nscope   2 project(s): NexusMem, uploader\n\n- 2026-08-12 [uploader] fix: raise the retry budget after the S3 upload timeouts\n- 2026-08-12 [uploader] retry.ts @ 8d0f98b — fix: raise the retry budget after the S3 upload timeouts\n  @@ -1 +1 @@\n  -export const RETRY_BUDGET = 3;\n  +export const RETRY_BUDGET = 5;\n- 2026-08-09 [NexusMem] fix(git): retry a transient failure to spawn git\n```\n\nDatabases stay per-repository — there is no shared global store, and deleting one repo's\n`.nexusmem/`\n\nstill removes exactly that repo's memory. What makes the others findable is a plain\nindex at `~/.nexusmem/projects.json`\n\n, written by `init`\n\nand refreshed by every `sync`\n\n. `nexusmem projects`\n\nshows what is in it, and `--prune`\n\nforgets entries whose database is gone.\n\nRanking across repositories uses reciprocal rank fusion per project rather than raw BM25, because a\nBM25 cost is computed against its own corpus and means different things in a 50-node and a\n50,000-node database. The trade is stated in *Where it breaks*.\n\nThe MCP `search_memory`\n\ntool takes the same switch as `allProjects: true`\n\n.\n\n```\n<repo>/.nexusmem/\n  .gitignore     '*' — the workspace ignores itself, so init never edits a file it doesn't own\n  config.json    validated on read; a corrupt config fails loudly rather than silently\n  memory.db      SQLite in WAL mode\n\n~/.nexusmem/\n  projects.json      which repositories exist, for cross-project recall; a corrupt one reads as empty\n  shell-history.jsonl  the hook's log, if you installed it\n```\n\n`NEXUSMEM_HOME`\n\noverrides the user-scoped directory.\n\nNode ids are content-addressed from `sha256(projectId + kind + naturalKey)`\n\n, so running `sync`\n\ntwice\ncannot produce duplicates and ingestion stays correct even if a cursor is lost. Project identity\ncomes from the normalized origin URL when there is one, falling back to the absolute path, so two\nclones of the same repo share one memory namespace.\n\nDeleting `.nexusmem/`\n\nloses nothing that `sync`\n\ncannot rebuild.\n\nIngestion, hybrid retrieval, budgeted packing and the MCP server all work and are covered by 315 tests running on Linux and Windows across Node 22 and 24. Phase 3 is complete.\n\n```\nnpm install\nnpm run typecheck\nnpm test\nnpm run build\n```\n\nTests are behavioral rather than snapshot-based, and several are regressions tied to specific\nobserved failures. `tests/git-errors.test.ts`\n\ninjects a fake `spawn`\n\nto exercise the Windows\nprocess-spawn faults, which cannot be provoked on demand.\n\nThis started as an experiment in whether a local context-memory engine for coding agents was viable, prototyped with Claude Code. The code was written through AI-assisted workflows; the architecture, the design decisions and the specifications were human-directed.\n\nThat is worth stating plainly because it should change how you read the code, not whether you trust\nit. Audits, corrections and PRs are genuinely welcome, and the commit history is deliberately\ndetailed about *why* things are the way they are, including the times an earlier assumption turned\nout to be wrong.\n\nMIT", "url": "https://wpnews.pro/news/show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log", "canonical_source": "https://github.com/yaminbkk/NexusMem", "published_at": "2026-08-15 05:32:15+00:00", "updated_at": "2026-08-15 05:41:27.581164+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "machine-learning"], "entities": ["NexusMem", "SQLite", "BM25", "FTS5", "sqlite-vec", "Reciprocal Rank Fusion", "Ollama", "better-sqlite3"], "alternates": {"html": "https://wpnews.pro/news/show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log", "markdown": "https://wpnews.pro/news/show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log.md", "text": "https://wpnews.pro/news/show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log.txt", "jsonld": "https://wpnews.pro/news/show-hn-nexusmem-local-memory-for-coding-agents-not-just-git-log.jsonld"}}