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 SQLite with FTS5, embeddings and a wiki-link graph, and exposes it to any MCP client as search, graph queries and agent memories. Retrieval returns ranked evidence and your AI does the reasoning — no model runs while you wait on a query. NeuroStack then keeps the base accurate: it flags notes that have gone stale, harvests decisions and root causes from AI sessions into memories, synthesises recurring memories into learnings, and queues proven ones for promotion into notes. Indexing never modifies your files. Optional MCP write tools let a client author or edit notes through your git history.

npm install -g neurostack && neurostack init

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

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.

Related MCP server: brain-mcp

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. It does everything else automatically.

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.

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:

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

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

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

What makes it different

NeuroStack is not a replacement for Obsidian, Notion, or any note-taking app. It sits on top of what you already use and adds what they don't have.

Stale detection is the part other tools lack. When a note keeps appearing in contexts where it no longer fits, such as a deprecated API or a superseded paper, NeuroStack flags it and demotes it in later results.

Profession packs

When you run neurostack init, you choose a profession pack. Each one configures NeuroStack with templates, folder structures, and AI guidance suited to how your profession actually uses notes.

Apply a pack to an existing vault without losing any notes:

neurostack scaffold researcher ~/my-notes    # or: writer, student, developer, devops, data-scientist

You can also import an existing Markdown directory:

neurostack onboard ~/my-notes

How retrieval works

Most memory tools give your AI a wall of text and let it figure out what's relevant. NeuroStack is tiered. It starts with the cheapest retrieval that answers the question and escalates only when it needs to.

Simple factual questions resolve at ~15 tokens. Deep dives get full context. Your AI spends its attention budget where it matters.

Your AI remembers decisions

Across sessions, your AI can save and retrieve typed memories: observations, decisions, conventions, learnings, bugs. When you start a new session, those memories are surfaced automatically.

"We decided to keep authentication stateless." "The thesis framing shifted from consolidation to complementary learning systems." "Elena's surname changed from Vasquez to Reyes in the chapter 7 revision."

These aren't just notes. They're things your AI remembers you decided together. They survive /clear. They survive closing the terminal. They survive switching machines.

neurostack memories add "revised thesis framing to CLS, not just consolidation" --type decision --tags "thesis,neuroscience"
neurostack memories search "thesis direction"

Learns from your AI sessions

NeuroStack scans your past AI conversations on a timer, extracts the decisions, observations and learnings, and saves them as memories. You do not have to write them down yourself.

neurostack harvest --sessions 5          # extract insights from last 5 sessions
neurostack hooks install                 # set up hourly auto-harvest

Supports Claude Code, VS Code, Codex CLI, Aider, and Gemini CLI session formats.

Keeps itself current

Your vault changes. NeuroStack watches it.

neurostack watch     # auto-index on vault changes

The index updates as you write and stale detection runs continuously, so you do not maintain it by hand.

What changes day-to-day

How your vault is stored

~/your-vault/                           # your Markdown files (not modified by indexing; AI clients can edit via opt-in MCP write tools)
~/.config/neurostack/config.toml        # configuration
~/.local/share/neurostack/
    neurostack.db                       # SQLite + FTS5 knowledge graph
    sessions.db                         # session transcript index

NeuroStack reads your vault. By default it writes nothing back, and all index data lives in its own SQLite databases. The opt-in MCP write tools (vault_write_file / vault_delete_file) are the one exception: they create or edit .md files in the vault and commit + push the change to your git remote on the spot.

Memory write-back (opt-in)

Memories live in SQLite by default, so they're invisible in Obsidian and vanish if the database is lost. Turn on write-back to persist qualifying memories as markdown files you own:

[writeback]
enabled = true                 # opt-in; default false
path = ".neurostack"           # quarantine dir, relative to vault_root
include_observations = false   # also write the noisier observation/context types

• Files land under {vault_root}/.neurostack/memories/<type>/<YYYY-MM>/<uuid>.md. NeuroStack only ever writes inside that one directory, so your own notes stay untouched.

• Only persistent (no-TTL) decision / convention / learning / bug memories are written; ephemeral (TTL) memories never are.

• The database stays the source of truth; files are readable exports. vault_remember / vault_update_memory / vault_forget / vault_merge keep the files in step automatically.

• The directory self-ignores via its own .gitignore so memories stay out of git until you opt in (delete that file to version them). NeuroStack never commits on your behalf.

• neurostack migrate write-back [--dry-run] exports existing memories; neurostack sync reconciles files against the DB (the DB wins on conflict).

Search & retrieval

Context & insights

Memories

Sessions

Vault files (opt-in write surface — git-backed)

# Setup
neurostack init                          # one-command setup: deps, vault, index
neurostack init --mode full ~/brain      # non-interactive full mode
neurostack onboard ~/my-notes            # import existing Markdown notes
neurostack scaffold researcher           # apply a profession pack
neurostack scaffold --list               # see all packs
neurostack update                        # pull latest source + re-sync deps
neurostack uninstall                     # complete removal

# Search & retrieval
neurostack search "query"                # hybrid search
neurostack tiered "query"                # tiered: triples -> summaries -> full
neurostack triples "query"               # knowledge graph triples
neurostack summary "note.md"             # AI-generated note summary
neurostack related "note.md"             # semantically similar notes
neurostack graph "note.md"               # wiki-link neighborhood
neurostack communities query "topic"     # GraphRAG across topic clusters
neurostack context "task" --budget 2000  # task-scoped context recovery
neurostack brief                         # session briefing

# Maintenance
neurostack index                         # build/rebuild knowledge graph
neurostack watch                         # auto-index on vault changes
neurostack decay                         # excitability report
neurostack prediction-errors             # stale note detection
neurostack backfill [summaries|triples|all]
neurostack communities build             # rebuild topic clusters
neurostack reembed-chunks                # re-embed all chunks
neurostack export --include triples -o dump.json  # dump index data as JSON

# Memories
neurostack memories add "text" --type observation
neurostack memories search "query"
neurostack memories list
neurostack memories update <id> --content "revised"
neurostack memories merge <target> <source>
neurostack memories forget <id>
neurostack memories prune --expired

# Sessions
neurostack harvest --sessions 5          # extract session insights
neurostack sessions search "query"       # search transcripts
neurostack hooks install                 # decay timer (default --type)

# Harness hooks (session brief, auto-RAG, trigger memories, checkpoints)
neurostack hooks install --harness claude   # or: omp
neurostack hooks status

# Trigger memories: did the warnings change anything?
neurostack triggers stats                # fired, followed, ignored per memory (30d)
neurostack triggers stats --days 7

# Checkpoint: manual only — a harness never fires one on its own (issue #176).
# `/save` (both harnesses) queues a request instead of running one directly:
neurostack hook enqueue --harness claude    # or: omp — POSTs to client.toml's queue_url
neurostack hook checkpoint --run --session <id>  # what the queue's worker runs
neurostack hook checkpoint --save               # a model's JSON reply on stdin

# Client setup
neurostack setup-client cursor           # or: windsurf, gemini, vscode, claude-code
neurostack setup-client --list
neurostack setup-desktop                 # Claude Desktop

# Diagnostics
neurostack stats                         # index health
neurostack doctor                        # validate all subsystems
neurostack demo                          # interactive demo with sample vault

Checkpoint runners use a nonblocking OS lock per conversation. Overlapping saves for one conversation return checkpoint already running, while separate conversations can save at the same time. The runner keeps the extracted reply and a receipt for each acknowledged item, so a partial retry does not call the model again or repeat confirmed saves. Each conversation retains the 256 most recent SHA-256 receipts of exact redacted content. Changed facts produce different receipts. A connection can still fail after the server commits but before it acknowledges the write. Avoiding that remote duplicate requires server-side idempotency, which the current vault_remember contract does not provide.

No harness fires a checkpoint on its own: /save is the only trigger, and it hands the request to a server-side queue named by queue_url in client.toml instead of running one directly. neurostack hook enqueue --harness <claude|omp> POSTs the request and prints one line back — queued, already queued, the daily cap reached, or unreachable — and exits 0 on a landed request, 1 otherwise. neurostack status shows the configured queue_url under LEARN. Whatever runs the actual checkpoint (a queue worker, a timer, herdr) passes --format omp or --format claude-code to checkpoint --run so it knows which transcript root to search when nothing is piped in on stdin.

Each feature models a specific mechanism from memory neuroscience:

Full citations: docs/neuroscience-appendix.md

FAQ

Does it modify my vault files? Not by default. Indexing, search, summaries, and every read tool leave your files untouched, and all index data lives in NeuroStack's own SQLite databases. Four opt-in MCP write tools (vault_write_file, vault_delete_file, plus vault_read_file / vault_list_files) let an AI client author and edit notes; every write commits and pushes to your git remote, so changes are tracked and revertable. If your vault is not a git repo, the file is still written to disk but the commit step is skipped. Separately, opt-in memory write-back persists memories as markdown, but only inside the quarantined .neurostack/ directory, away from your own notes.

Do I need a GPU? No. Lite mode has zero ML dependencies. Full mode runs on CPU but summarization is slow without a GPU.

Do I need to know Python? No. The npm package handles everything. You never touch a virtualenv.

How large a vault can it handle? Tested with ~5,000 notes. FTS5 search stays fast at any size.

Can I use it without an AI client? Yes. The CLI works standalone and pipes into any LLM.

Is my vault private? Yes. Nothing leaves your machine, unless you point Full mode at a third-party LLM provider instead of local Ollama. In that case the text you index goes to that provider under its own policy.

What AI clients does it work with? Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code, Codex and any other client that supports MCP.

Requirements

• Linux or macOS

• Lite mode: Node.js + Python 3.11+. No GPU or Ollama required.

• Full mode: Ollama with nomic-embed-text and a summary model. GPU or 6+ core CPU recommended.

Get started

npm install -g neurostack
neurostack init

neurostack init picks a tier, installs dependencies, indexes the vault and configures your MCP client.

• Contributing: CONTRIBUTING.md

• GitHub: github.com/raphasouthall/neurostack

• Sponsor: GitHub Sponsors | Buy me a coffee

Apache-2.0, see LICENSE. No GPL dependencies.