# nexusmem

Local-first memory engine for coding assistants that tracks shell history, exit codes, and git diffs. Keeps agents from repeating broken steps and dead ends.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 15
- Author: yaminbkk
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/yaminbkk/NexusMem
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/nexusmem

## What it does

NexusMem records developer activity into a local SQLite file on disk. The tool logs shell executions alongside their true exit codes, per-file git patches, and markdown docs. When an agent queries its background, the ranker returns relevant items fitted to a specified token budget without sending project data to cloud services.

Custom hooks expand this tracking to the interactive shell and the agent environment. The shell hook captures the working directory with status codes, while the Claude Code hook associates test executions with prior file edits. Commands are automatically scrubbed of credentials before being stored.

Running on Node 20 will fail immediately due to missing `better-sqlite3` binaries. You need git and Node version 22 or newer on your machine. An Ollama instance is entirely optional and only comes into play for vector search.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add nexusmem -- npx -y nexusmem
```

### Codex

**Platform CLI**
```bash
codex mcp add nexusmem -- npx -y nexusmem
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "nexusmem": {
            "command": "npx",
            "args": [
                "-y",
                "nexusmem"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nexusmem": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "nexusmem"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add nexusmem npx -y nexusmem
```

## When to use it
- record terminal command execution with real exit codes
- surface past solutions for broken builds and tests
- retrieve relevant git patches within strict token limits
- prevent coding assistants from repeating failed shell commands

## Example prompts
- Search NexusMem history to see why our build failed earlier and how it was resolved
- Find previous commands in nexusmem related to process spawn failures on Windows

## Similar
- [context-sync](https://affpapa.org/en/nevibecode/mcp/context-sync.md) — MCP server · ★ 189
- [Palinode](https://affpapa.org/en/nevibecode/mcp/palinode.md) — MCP server · ★ 46
- [callimachus](https://affpapa.org/en/nevibecode/mcp/callimachus.md) — MCP server · ★ 46
- [openchronicle-mcp](https://affpapa.org/en/nevibecode/mcp/openchronicle-mcp.md) — MCP server · ★ 16
- [neverinfamous-memory-journal-mcp](https://affpapa.org/en/nevibecode/mcp/neverinfamous-memory-journal-mcp.md) — MCP server · ★ 20
- [Memorix](https://affpapa.org/en/nevibecode/mcp/memorix.md) — MCP server · ★ 873

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md