# sqlite-graph-memory

Gives coding agents associative long-term memory over markdown notes. It pairs dense vector retrieval with existing [[wikilinks]] using SQLite and zero external graph databases.

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

## What it does

The server turns a folder of markdown files, such as an Obsidian vault, into an associative memory store for coding agents. A preprocessing tool called `sgm-index` splits text into chunks and generates `e5-base` embeddings. During query execution, the pipeline retrieves entry points via vector similarity, pulls linked notes using `[[wikilinks]]` syntax up to one hop away, and scores the final context with a cross-encoder.

Graph edges are not stored in dedicated graph infrastructure. The retrieval script inspects links directly from markdown files at query time, capping graph expansion at 40 neighbor documents. Derived turn state persists in a single local SQLite file via Python standard library drivers. The server will not start without setting `BRAIN_INDEX_DIR` to the location of the precomputed index directory.

It also captures session telemetry via an assistant turn hook. The script parses the end of the conversation transcript and appends summaries, file edits, and tool decisions into SQLite without spending extra model tokens.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `BRAIN_INDEX_DIR`, `TURNSTATE_DB` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env BRAIN_INDEX_DIR=<BRAIN_INDEX_DIR> --env TURNSTATE_DB=<TURNSTATE_DB> --transport stdio sqlite-graph-memory -- uvx sqlite-graph-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sqlite-graph-memory <command>

### Codex

**Platform CLI**
```bash
codex mcp add sqlite-graph-memory --env BRAIN_INDEX_DIR=<BRAIN_INDEX_DIR> --env TURNSTATE_DB=<TURNSTATE_DB> -- uvx sqlite-graph-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sqlite-graph-memory <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "sqlite-graph-memory": {
            "command": "uvx",
            "args": [
                "sqlite-graph-memory"
            ],
            "env": {
                "BRAIN_INDEX_DIR": "<BRAIN_INDEX_DIR>",
                "TURNSTATE_DB": "<TURNSTATE_DB>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sqlite-graph-memory <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "sqlite-graph-memory": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "sqlite-graph-memory"
            ],
            "env": {
                "BRAIN_INDEX_DIR": "<BRAIN_INDEX_DIR>",
                "TURNSTATE_DB": "<TURNSTATE_DB>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sqlite-graph-memory <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e BRAIN_INDEX_DIR=<BRAIN_INDEX_DIR> -e TURNSTATE_DB=<TURNSTATE_DB> sqlite-graph-memory uvx sqlite-graph-memory
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from sqlite-graph-memory <command>

## When to use it
- recall context from personal markdown notes and Obsidian vaults
- traverse `[[wikilinks]]` connections without running a graph database
- rerank associative retrieval results using a local cross-encoder
- record agent session summaries and tool execution logs into SQLite

## Example prompts
- Search my notes for project architecture details and linked design specs.
- Look up Lanternfish in my Obsidian notes and retrieve connected project documents.
- Check recent agent turn history in the database for decisions made on the schema.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

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