NexusMem

# NexusMem

[![CI](https://github.com/yaminbkk/NexusMem/actions/workflows/ci.yml/badge.svg)](https://github.com/yaminbkk/NexusMem/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/nexusmem)](https://www.npmjs.com/package/nexusmem)
[![npm downloads](https://img.shields.io/npm/dm/nexusmem)](https://www.npmjs.com/package/nexusmem)
[![License: MIT](https://img.shields.io/badge/license-MIT-informational)](LICENSE)
![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)

![NexusMem: init, sync, status, and a query against this repo's own history](docs/demo.gif)

Your coding agent can read `git log`. It cannot read the four things you tried last Tuesday that
didn't work.

NexusMem 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.

The 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.

**Contents:** [Try it](#try-it) · [Exact shell capture](#optional-exact-shell-capture) ·
[Failure → fix chains](#failure--fix-chains-opt-in) · [How retrieval works](#how-retrieval-works) ·
[Session summaries](#session-summaries-optional-local-model) · [Use it from an agent](#use-it-from-an-agent)
· [What it costs you](#what-it-costs-you) · [Manual staleness & provenance](#manual-staleness--provenance) ·
[Where it breaks](#where-it-breaks) · [Commands](#commands) · [Cross-project recall](#recall-across-projects)
· [On disk](#on-disk) · [Development](#development)

## Try it

From inside any git repository:

```
npx nexusmem init
npx nexusmem sync
```

Then ask it something. Real output from this repository, top 2 of 5 hits:

```
$ nexusmem query "windows spawn failure"

Relevant history for: windows spawn failure

- 2026-08-09 [observed] fix: distinguish a failed git spawn from "not a git repository"
  readRepoInfo collapsed three unrelated failures into one error: git running and reporting
  the path is not a work tree, git not being installed, and the process failing to spawn at
  all. Dogfooding hit the third case in two separate sessions...
- 2026-08-09 [inferred] README.md — Before a tagged release
  - [ ] Retry on transient process-spawn failures on Windows
```

`[observed]`/`[inferred]` is the provenance tag (see [Manual staleness & provenance](#manual-staleness--provenance))
— a commit is a directly observed event, a doc section is a written claim that could go stale.

A 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.)

For a sense of what actually accumulates, here is `nexusmem status` on this repo after two days:

```
527 node(s)  2026-08-08 .. 2026-08-09
       321  shell_command
       130  conversation_turn
        60  doc_section
        16  git_commit
```

Sixteen commits. Three hundred and twenty-one shell commands. The commits were already retrievable
by any agent with a terminal. The rest was not.

That `conversation_turn` row only appears because this corpus was synced with `--conversation`.
Assistant transcripts are the one source that is off by default and stays off until you opt in, since
they are the likeliest place for a pasted credential to be sitting. A default install indexes git
commits, their diffs, shell and docs.

Requirements: Node 22 or newer, and git. Node 20 will not work, because `better-sqlite3` ships no
prebuilt binary for it and Node 20 went end-of-life in April 2026. Ollama is optional and only
affects semantic search (see below).

## Optional: exact shell capture

Scraped history files (PSReadLine, `.bash_history`, `.zsh_history`) give you command text and not
much else. The hook gives you working directory, exit code and a real timestamp:

```bash
nexusmem hook install
```

It wraps your existing PowerShell prompt rather than replacing it, is idempotent, and
`nexusmem hook remove` undoes it cleanly.

Exit 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.

## Failure → fix chains (opt-in)

```bash
nexusmem sync --link-failures
```

After a normal sync, this walks every failed `shell_command` (non-zero exit code) and looks for
whatever later resolved it, using two independent heuristics: a later command in the same project
and working directory, exact same normalized text, that exited `0` within 24h (**same-command
retry**); and, separately, the best full-text match among nearby conversation turns or session
summaries, requiring every significant word of the failing command to appear, not just one
(**conversation bridge**). A failure can be linked by either, both, or neither.

Both links are surfaced in query results. The conversation-bridge heuristic originally matched on
any shared word, and dogfooding against this repo's own real history found it wrong on roughly half
its links — a shared word as generic as "npm" was enough to link an unrelated discussion. Requiring
every significant word fixed that: re-dogfooded against the same corpus, every resulting link (the
full set produced, not a sample) checked out correct on manual review of the full text, not just the
summary.

When a linked failure appears in a result set, its fix rides along immediately after it, inheriting
the failure's own relevance score rather than needing to match the query on its own merits. That is
the point: a query about why something failed shouldn't need to separately guess the words used in
whatever fixed it. This works across projects too — `query --all-projects` chains a failure to its
fix using whichever project's own database recorded the link, since links are always local to the
project they were found in.

```
$ nexusmem query "why did npm whoami fail"

- 2026-08-12 [observed] shell: npm whoami  (exit 1)
- 2026-08-12 [observed] shell: npm login   (exit 0)  -- linked as the fix
```

## How retrieval works

Every source normalizes to the same `MemoryNode` shape, so a commit, a shell command and a docs
section compete on equal terms. Retrieval runs BM25 over FTS5 and, if an embedding model is
reachable, a vector search over `sqlite-vec`, fused with Reciprocal Rank Fusion on rank *position*
only, never raw scores — a BM25 cost and a vector distance live on unrelated, unbounded scales, and
position is the only thing they agree on.

Ranking then multiplies three factors:

```
score = relevance × signal^0.215 × recency^0.288
```

`relevance` comes from the query. `signal` (a `fix:` commit outranks a `chore:`; a failed command
outranks a successful one) and `recency` are priors that hold before any query exists. Each factor is
floored into `[floor, 1]` rather than `[0, 1]`, so one weak dimension can't zero out a strong match.

The exponents bound how far signal and recency, *together*, may overturn relevance: at most a 2× gap
across their whole range, applied jointly rather than per-prior. That's deliberate — the score
*multiplies* the two priors, so capping each at 2× separately still let the pair overturn 4×, and
that hit hardest on fresh, high-signal commits made during an active working day. The bug that
exposed this: two unrelated same-day `fix:` commits outranked the docs section that actually answered
the query. See [`retrieval/rank.ts`](src/retrieval/rank.ts) for the full derivation.

Without Ollama, vector search is skipped and you get BM25 only — fully supported, not a degraded
state; `sync` and `query` both succeed and simply do less.

## Session summaries (optional, local model)

With `sources.session.enabled`, each finished session becomes one distilled node next to the raw
exchanges — what was decided and why, rather than forty individual turns. It runs a local Ollama
chat model (`qwen2.5:3b` by default); nothing is downloaded automatically and nothing leaves the
machine.

```bash
nexusmem scan-session --dry-run
```

That prints the exact prompt a session would produce, after redaction and budget trimming, without
calling the model.

Three things bound the cost. A session is only summarized once it has been quiet for
`settleMinutes` (default 30), so a session in progress is not re-summarized on every sync. The
prompt is hashed, and an unchanged hash skips the model entirely — on this repo a steady-state sync
of 14 summarized sessions takes 0.25s and makes no model calls. And `maxSessions` (default 10) caps
how many reach the model per run; the rest are reported as queued and picked up next sync.

**What it is actually like, measured on 14 real sessions with `qwen2.5:3b`.** The summaries
themselves are good: decisions with their reasons, in the shape the prompt asks for. Titles are less
reliable — the model returned a usable one about a third of the time, and otherwise produced a
conversational preamble, a stray bullet, or a bare "Summary of the Session". Those are rejected and
the title falls back to the first line of the question that opened the session, which is always
specific even when it is not elegant. Compliance was worst on long sessions and on transcripts not
in English. A larger model (`qwen2.5:7b`) is the lever if the titles matter to you; set
`sources.session.model`.

## Use it from an agent

```json
{
  "mcpServers": {
    "nexusmem": {
      "command": "npx",
      "args": ["-y", "nexusmem", "mcp"]
    }
  }
}
```

Three tools over stdio: `search_memory` returns the packed cont