{"slug": "show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents", "title": "Show HN: NexusMem – Local context memory engine for AI coding agents", "summary": "NexusMem, a local-first persistent memory engine for AI coding agents such as Claude Code, Cursor, and MCP-based agents, records git history, shell commands, docs, and conversation transcripts into an on-disk SQLite database, returning only relevant context within a token budget. All data remains local with no cloud dependencies, and it uses hybrid search combining BM25 and vector search via sqlite-vec and Ollama, with ranked, budgeted retrieval. The project is available on GitHub and supports MCP tools for Claude Desktop, Cursor, and Windsurf.", "body_md": "A local-first persistent memory engine for AI coding agents (Claude Code, Cursor, MCP-based agents).\n\nAI coding assistants forget context once a session ends, and re-uploading the entire repository as context on every request is slow and expensive. NexusMem records local machine events — git history, shell commands, docs, and conversation transcripts — into an on-disk SQLite database, returning only the relevant context slice within a strict token budget.\n\nAll data remains local on your machine. No cloud dependencies, accounts, or telemetry.\n\n**100% Local-First**: SQLite database stored in`.nexusmem/`\n\ninside your repository using`sqlite-vec`\n\nand`FTS5`\n\n. Works fully offline.**Kind-Agnostic Core**: Every source normalizes to a single`MemoryNode`\n\nschema, allowing git commits, shell commands, and documentation to be scored and ranked on an equal basis.**Hybrid Search (BM25 + Vector)**: Combines exact keyword matching via SQLite FTS5 (BM25) with semantic vector search (`sqlite-vec`\n\nvia a local Ollama model) using Reciprocal Rank Fusion (RRF). RRF fuses on rank position only, never on raw scores, which is what makes it safe to combine a BM25 cost with a vector distance on an unrelated scale. Degrades gracefully to BM25-only if Ollama is offline.**Ranked, Budgeted Retrieval**: Scores candidates using`score = relevance × signal^a × recency^b`\n\n, then packs nodes into a caller-specified token budget. Each factor is floored into`[floor, 1]`\n\nrather than`[0, 1]`\n\n, so no single low factor can zero out a strong match. The exponents`a`\n\nand`b`\n\nare derived, not tuned:`relevance`\n\nis the only query-derived factor, so each query-independent prior is raised to the power that caps its entire range at overturning a 2× relevance gap (`span^exponent = 2`\n\n, giving`a ≈ 0.431`\n\n,`b ≈ 0.576`\n\n).**MCP Server Native**: Exposes`search_memory`\n\n,`sync_project`\n\n, and`get_status`\n\nas Model Context Protocol (MCP) tools over stdio for Claude Desktop, Cursor, and Windsurf.\n\n```\ngit / shell / docs / transcripts\n              │\n              ▼   collectors/    normalize to one MemoryNode shape\n              │\n              ▼   store/         SQLite (FTS5 + sqlite-vec)\n              │\n              ▼   retrieval/     RRF fuse -> rank -> pack to token budget\n```\n\n**Git Collector**: Ingests commits, diff statistics, renames, and conventional commit signals incrementally via stream iterators. Sync cursors are validated as ancestors of`HEAD`\n\nbefore being trusted, so a rebase or amend widens the walk instead of silently skipping commits.**Shell Collector**: Scrapes default history files (`PSReadLine`\n\n,`.bash_history`\n\n,`.zsh_history`\n\n). An optional PowerShell profile hook upgrades capture to include exact timestamps, working directories, and exit codes (where failed commands receive a higher structural signal).**Docs Collector**: Indexes Markdown documentation (`.md`\n\nfiles) tracked by git. Line endings are normalized to LF before chunking to prevent CRLF splitting failures on Windows. Scoped pruning removes orphaned sections when headings are renamed or deleted, scoped by project and exact source so it cannot affect git, shell, or conversation nodes.**Conversation Collector**(opt-in): Indexes AI assistant transcripts, redacting secrets before writing to disk. Replies are chunked at heading and bold-lead boundaries rather than stored as whole exchanges.\n\nNode ids are content-addressed (`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 is\nderived from the normalized origin URL when one exists, falling back to the absolute path, so two\nclones of the same repository share one memory namespace.\n\n`nodes_fts`\n\nis trigger-populated and stays consistent automatically. `nodes_vec`\n\nis not — computing\nan embedding requires an async call to Ollama, which a synchronous SQL trigger cannot make — so it is\nfilled by an explicit pass after `sync`\n\nwrites nodes, and a node whose content changes has its stale\nembedding dropped for re-embedding.\n\n- Node.js ≥ 20.11\n- Git\n- Local Ollama instance with an embedding model (optional, for vector search)\n\n```\ngit clone https://github.com/yaminbakoh4-dot/NexusMem.git\ncd NexusMem\nnpm install\nnpm run build\nnpm link\n```\n\n`npm link`\n\nputs `nexusmem`\n\non your `PATH`\n\n, so it runs against any repository on your machine.\n\nRun from any git repository:\n\n```\nnexusmem init\nnexusmem sync\nnexusmem query \"why does the retry logic exist\"\n```\n\nTo capture exact working directory and exit status for shell history:\n\n```\nnexusmem hook install\n```\n\nThis wraps your existing PowerShell prompt rather than replacing it, is idempotent, and is undone\ncleanly by `nexusmem hook remove`\n\n.\n\nAdd the following to your MCP client configuration file:\n\n```\n{\n  \"mcpServers\": {\n    \"nexusmem\": {\n      \"command\": \"nexusmem\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nAvailable tools:\n\n| Tool | Description |\n|---|---|\n`search_memory` |\nSearches and ranks memory for a given prompt within a token budget. |\n`sync_project` |\nRuns ingestion and updates embeddings for the specified repository root. |\n`get_status` |\nReturns current ingestion counts and database state per source. |\n\nEach tool takes an explicit `projectRoot`\n\n, because MCP tool calls carry no implicit shell working\ndirectory. `sync_project`\n\nruns `init`\n\nfirst automatically if the repository has not been set up yet.\n\nNexusMem distinguishes between **packer efficiency** (internal packing performance against candidate\nsets) and **end-to-end token savings** (real-world savings on the context bill). The two are not\ninterchangeable, and quoting the first as if it were the second is the specific overclaim this\nsection exists to prevent.\n\nMeasures how effectively the ranking packer drops low-scoring candidate nodes relative to the raw candidate body sum within a strict token budget:\n\n| Scenario | Candidate Corpus | Result |\n|---|---|---|\n| Fixture repo (tight budget, 3 matches, 1 dropped) | 23 commits | 25% |\n| Fixture repo (generous budget, 6 matches, all kept) | 23 commits | -15% (overhead exceeds trim) |\n| Core repo design evaluation | 515 nodes | 81% – 84% |\n\nEfficiency is derived from excluding irrelevant low-scoring candidates entirely, not from text summarization. It increases with corpus size and goes negative on a tiny one, where fixed per-node formatting overhead outweighs the little there is to trim.\n\nThe baseline it divides by is hypothetical: without NexusMem those candidate bodies would never have entered the context window at all. This figure is useful for tuning the ranker, not as a claim about a session's token bill.\n\nMeasures packed context size against reading the equivalent full source files into context.\n\n**Measured result: ~40%** on design queries evaluated against this codebase (reading `README.md`\n\n+\n`docs/phase-2-spec.md`\n\nin full, ~32k chars ≈ 8–9k tokens, versus retrieving relevant packed context).\nHand-tallied from one real session, not instrumented — treat it as an order-of-magnitude figure.\n\n**The long-term >70% target is not met at this scale, and this repository cannot demonstrate it.**\nThe target describes large repositories (thousands of commits) where the win comes from omitting\nhundreds of unrelated history items rather than shaving a handful. A benchmark against a repository\nof that size is still outstanding.\n\nOne caveat in NexusMem's favour is not a percentage at all: the conversation turns and shell commands\nin memory have no cheap `grep`\n\nequivalent. Without a collector recording them they are gone, not\nmerely more expensive to retrieve.\n\nMeasured on this repository's corpus (~530 nodes), warm, p50 over 10 runs:\n\n| Operation | Latency |\n|---|---|\n| BM25-only retrieval pipeline (FTS5) | ~1.1 ms |\nVector search (`sqlite-vec` KNN) |\n~3.2 ms |\n| RRF fuse + rank + pack | ~0.6 ms |\n| Query embedding (local Ollama call) | ~55–77 ms |\n| End-to-end hybrid retrieval | ~56 ms |\n\nAll SQLite-side work totals roughly 5 ms. The end-to-end figure is dominated by the local embedding call, which is the only meaningful latency target on this path.\n\n| Command | Description |\n|---|---|\n`nexusmem init` |\nInitializes `.nexusmem/` directory and SQLite schema. |\n`nexusmem sync` |\nIngests new events (git, shell, docs; `--conversation` for transcripts). |\n`nexusmem status` |\nPrints memory counts per source and database status. |\n`nexusmem query <text>` |\nExecutes hybrid search, ranks, and packs context to stdout. |\n`nexusmem scan-git` |\nDry-run preview of git nodes and signal scores without writing to DB. |\n`nexusmem scan-shell` |\nDry-run preview of shell history nodes without writing to DB. |\n`nexusmem scan-docs` |\nDry-run preview of doc section nodes without writing to DB. |\n`nexusmem scan-conversation` |\nDry-run preview of conversation nodes without writing to DB. |\n`nexusmem hook install` |\nInstalls PowerShell profile wrapper for high-precision shell logs. |\n`nexusmem hook remove` |\nRemoves the PowerShell profile wrapper. |\n`nexusmem hook status` |\nReports whether the hook is installed. |\n`nexusmem mcp` |\nStarts the MCP stdio server. |\n\nEvery command accepts `-C, --cwd <path>`\n\nto target a repository other than the current directory.\nUseful `sync`\n\nflags: `--conversation`\n\nopts the conversation source in for one run without persisting\nit to config; `--no-embed`\n\nskips the vector-embedding pass; `--rebuild`\n\ndrops the project's nodes and\nre-ingests from scratch.\n\n```\n<repo>/.nexusmem/\n  .gitignore     '*' — the workspace ignores itself, so init never edits a file it does not own\n  config.json    validated on read; a corrupt config fails loudly, never silently\n  memory.db      SQLite (WAL): nodes, node_files, nodes_fts, nodes_vec, sync_state\n```\n\nDeleting `.nexusmem/`\n\nloses nothing that `sync`\n\ncannot rebuild.\n\n**Windows Line Endings**: Markdown files are normalized from CRLF to LF prior to chunking. Un-normalized CRLF causes the paragraph splitter (`\\n{2,}`\n\n) to never fire —`\\r\\n\\r\\n`\n\ncontains no two consecutive`\\n`\n\n— collapsing an entire file into a few coarse, heading-less blocks.**Git Rebase / Amend**: Rewriting git history leaves orphaned nodes for unreachable commits. These are real events, so they are not wrong, but a targeted prune does not exist yet;`sync --rebuild`\n\nforces a clean re-scan if required.**Non-Segmented Languages**: FTS5`unicode61`\n\ntokenization splits on whitespace. Languages without space boundaries (Thai, Japanese, Chinese) rely on the vector search pass for recall.**Unscoped Shell History**: Scraped shell history files without the PowerShell hook lack directory context and are attributed to whichever repository`sync`\n\nwas executed from. Bounded to the tail window, and an approximation rather than a guarantee.**PSReadLine Multi-Line Entries**: A function typed across several lines at the prompt is read as separate single-line commands, not reconstructed.** Scrape-Fallback Id Drift**: Position-based ids for the scrape fallbacks can drift if the underlying history file is trimmed from the front between syncs. Installing the hook fixes this.**Conversation Retrieval Precision**: Chunking replies at heading boundaries improved precision on long replies but has not been evaluated systematically.** Embedding Batch Size**: The embedding pass processes a bounded batch per`sync`\n\n; a large corpus needs several runs to embed fully.\n\nPhases 1 and 2 are shipped. Phase 3 is in progress.\n\n-\n`init`\n\n/`sync`\n\n/`query`\n\ncommand surface - Git collector (commits, diff stats, renames, conventional-commit signal)\n- Shell collector (PSReadLine, bash, zsh) with optional PowerShell hook\n- SQLite storage with FTS5/BM25\n- Token-budgeted context packing\n\n-\n`sqlite-vec`\n\nembeddings via a local Ollama model - Reciprocal Rank Fusion over BM25 + vector results\n- MCP server (stdio):\n`search_memory`\n\n,`sync_project`\n\n,`get_status`\n\n- Conversation collector (opt-in), chunked below whole-exchange granularity\n\n- Docs collector for tracked Markdown files\n- Scoped pruning of orphaned doc sections on re-sync\n- Diff-level nodes (currently commit-level only)\n- Session summarization via a local SLM\n- Cross-project recall (queries are scoped to one project today)\n- Batch the embedding pass (capped at 200 nodes per\n`sync`\n\n)\n\n- CI\n- Retry on transient process-spawn failures on Windows\n- Benchmark against a large repository — the >70% end-to-end target is unproven at this corpus size, where ~40% is what was measured\n\n```\nnpm install\nnpm run typecheck\nnpm test\nnpm run build\n```\n\n`scan-git`\n\n, `scan-shell`\n\n, `scan-docs`\n\nand `scan-conversation`\n\nwrite nothing — they print the\n`MemoryNode`\n\ns ingestion would create, with their signal scores, which is the intended way to tune\nscoring against a real repository before committing to a schema change. Add `--json`\n\nto pipe the\noutput elsewhere.\n\nThere is no CI configured yet.\n\nThis project was initially prototyped and built using **Claude Code** to test the viability of local context memory engines for AI agents.\n\nWhile the codebase was generated through AI-assisted workflows, the architecture, system design, and product specifications were directed by human requirements. Contributions, code audits, and refactoring from the community are extremely welcome!\n\nMIT", "url": "https://wpnews.pro/news/show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents", "canonical_source": "https://github.com/yaminbakoh4-dot/NexusMem", "published_at": "2026-08-10 06:34:23+00:00", "updated_at": "2026-08-10 07:11:39.527252+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure", "machine-learning"], "entities": ["NexusMem", "Claude Code", "Cursor", "Windsurf", "SQLite", "Ollama", "Model Context Protocol", "Claude Desktop"], "alternates": {"html": "https://wpnews.pro/news/show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents", "markdown": "https://wpnews.pro/news/show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents.md", "text": "https://wpnews.pro/news/show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-nexusmem-local-context-memory-engine-for-ai-coding-agents.jsonld"}}