NeuroStack

A local retrieval layer and optimizer for the Markdown knowledge base you already have.

NeuroStack indexes a folder of .md files (Obsidian, Logseq, Notion exports, plain Markdown) into one SQLite database with full-text search, embeddings and a wiki-link graph. Any MCP client can then search it, walk the graph and save memories. A query returns ranked evidence with note paths, and your AI does the reasoning, so no model runs while you wait. Between queries NeuroStack keeps the knowledge base accurate. It flags notes that have gone stale, harvests decisions and root causes from your AI sessions, merges recurring memories into learnings, and queues the proven ones to become notes. Indexing never changes your files, and optional MCP write tools let a client edit notes through your git history.

Works with Claude, Cursor, Windsurf, Gemini CLI, VS Code, Codex and any other client that supports MCP.

60-second start

npm install -g neurostack          # install

neurostack init # pick your notes folder, press Enter for the rest /save # in omp or Claude Code, keep what this session learned neurostack doctor # check that everything works

The steps below explain each part and how to connect other AI clients.

---

Your notes, in your control

By default, NeuroStack is a read-only indexing layer:

• Indexing, search, summaries, and graph analysis never modify your Markdown files
• All index data lives in NeuroStack's own separate database
• To remove it completely, run neurostack uninstall. Your notes stay untouched.
• Nothing ever leaves your machine, unless you configure a third-party LLM provider for summaries and embeddings

If your vault is a git repo, four opt-in MCP write tools let an AI client author and edit notes for you: vault_write_file, vault_delete_file, plus vault_read_file / vault_list_files. Every write commits and pushes to your git remote with a descriptive message, so every change is visible in git log, revertable with git revert, and serialised under a per-vault lock. Writes hard-reject invalid frontmatter, paths outside the vault, and hidden directories (.git, .obsidian, …). Because the tools are exposed to any client talking to neurostack serve, gate them at the transport (auth, tunnel, LAN only) if you put the MCP endpoint on the public internet.

---

Who this is for

You do not need to be a developer. If you take notes in Markdown, or can export your notes as Markdown from Obsidian, Notion, Bear, or Roam, NeuroStack works for you.

---

Get started in three steps

You will need Node.js installed (most computers already have it). The npm package handles the Python setup for you.

Step 1. Install

npm install -g neurostack

Step 2. Set up (takes about two minutes)

neurostack init

The setup wizard asks which vault folder to index, which mode to run (Lite or Full), and which profession pack to apply. Then it finishes the install for you. It adds the NeuroStack hook to omp or Claude Code if you have them, so /save keeps what a session learned. It sets up the AI that turns saved sessions into memories, using the same model as your summaries. If no model answers yet, it leaves that off and tells you so. It also installs one background timer that keeps the index tidy, and a failed background job shows up as a desktop notification. Press Enter at each question to take the default. At the end it runs neurostack doctor and shows what to try first.

Step 3. Connect to your AI

For Claude Desktop:

neurostack setup-desktop

For Claude Code:

claude mcp add neurostack -- neurostack serve

For Cursor, Windsurf, Gemini CLI, or VS Code:

neurostack setup-client cursor      # or: windsurf, gemini, vscode

Done. Open a new conversation and ask your AI about something from your notes.

Lite and Full modes

Everything runs on your machine. Choose a tier during neurostack init:

• Lite (~130 MB) gives you keyword search, link-based connections between notes, stale detection and the MCP server. No GPU or Ollama required.
• Full (~560 MB) adds semantic search by meaning, AI-generated summaries, connections between notes, and topic clustering via local Ollama. GPU or 6+ core CPU recommended.

Non-interactive setup takes every default:

neurostack init --mode lite ~/my-notes --yes    # lite mode

neurostack init --mode full ~/my-notes --yes # full mode

--no-hooks, --no-schedule and --checkpoint none turn off the hook, the timer and the checkpoint AI.

Alternative install methods (PyPI, pip, curl)

# PyPI

pipx install neurostack pip install neurostack # inside a venv uv tool install neurostack

One-line script

curl -fsSL https://raw.githubusercontent.com/raphasouthall/neurostack/main/install.sh | bash

Lite mode (no ML deps)

curl -fsSL https://raw.githubusercontent.com/raphasouthall/neurostack/main/install.sh | NEUROSTACK_MODE=lite bash

On Ubuntu 23.04+, Debian 12+, and Fedora 38+, bare pip install outside a virtual environment is blocked by the operating system. Use npm, pipx, or uv tool install instead.

To uninstall: neurostack uninstall

---

What it does

• Hybrid search (FTS5 keyword + semantic) with tiered depth, so a client can fetch triples, summaries or full notes by token budget.
• Ranked evidence with note paths and excerpts over the CLI, MCP, or an OpenAI-compatible API, for your AI to cite and reason over.
• Stale detection. A note that keeps surfacing in contexts where it no longer fits is flagged and demoted in later results.
• Session harvest. A timer scans Claude Code, Codex, Gemini and omp transcripts and saves decisions, bugs, conventions and learnings as memories with TTLs.
• Synthesis and promotion. Recurring memories become learnings; a promotion queue lists which ones are ready to become notes.
• Wiki-link graph with PageRank, community detection, gap and bridge analysis.
• Read-only by default. Opt-in write tools commit and push every change to your git remote.

Technical pipeline (module by module)

Editable sources live in the .drawio files next to the images.

---

Design

Philosophy

1. Your files stay yours. The index lives in its own database, so deleting it leaves your notes exactly as they were.
2. NeuroStack returns evidence and your AI reasons over it. No tool answers questions, and tests/test_no_answering.py keeps it that way.
3. Removing a memory moves it to an archive that search cannot reach, and you can restore it later.
4. NeuroStack redacts secrets from text a model wrote, such as harvested summaries. It stores what you or your agent saved on purpose word for word.
5. Ranking changes get measured first. neurostack eval switches off usage learning while it runs, so one pass cannot skew the next.

Mental model

NeuroStack holds two layers and one loop.

The vault is your Markdown. NeuroStack reads it, splits it into chunks, embeds them, summarises each note, extracts facts as triples and builds the link graph. Note status and tags live in NeuroStack's own note_metadata table, so it never needs to edit your frontmatter.

The memory layer holds what agents learn, typed as observations, decisions, conventions, learnings, bugs or context. These rows belong to NeuroStack and carry an optional workspace and an optional expiry.

The optimizer loop runs on a timer and connects the two. A memory usually starts in an AI session, becomes a learning when it keeps recurring, and becomes a note once no existing note covers it.

Architecture

flowchart LR

V[/"Markdown vault never modified"/] --> IX["index chunk, embed, summarise, triples, link graph"] IX --> DB[("neurostack.db SQLite + FTS5")] S[/"AI session transcripts"/] --> H["harvest"] A["MCP client or CLI"] -->|vault_remember| DB H --> DB DB --> R["search, tiered, context, graph, brief"] R --> A DB --> J["timer jobs synthesize, promotion, decay, communities"] J --> DB J -->|opt-in, git commit| V DB --> UI["neurostack ui read-only dashboard"]

One OS timer runs neurostack run-due every minute, and that command runs each due job in turn. neurostack serve exposes 33 MCP tools over stdio or HTTP, and neurostack api serves the same retrieval as an OpenAI-compatible API.

Data model

A memory row stores its content, tags, type, workspace, source agent, embedding and expiry. It also records embed_pending when the embedder was down, so neurostack backfill can embed it later, plus revision_count and merged_from for edits and merges. A second database, sessions.db, indexes raw session transcripts for neurostack sessions search.

Write mechanics

1. Deliberate saves. vault_remember and neurostack memories add store the text as written, embed it once, then report any near