neurostack

<img src="docs/logo.svg" alt="NeuroStack" height="48">

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.

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.

| If you are... | NeuroStack helps you... | |--------------|------------------------| | A researcher | Ask your AI "what do my notes say about X?" across hundreds of papers. Get warned when a note references a retracted finding or superseded paper before your AI cites it confidently. | | A fiction writer | Your AI knows your world-building bible, character histories, and chapter decisions. It remembers that you agreed in session 4 that Elena's backstory changes in act 2. | | A student | Ask your AI to explain connections across all your course notes. When a syllabus topic changes, stale revision notes are flagged automatically. | | A professional | Your AI remembers client context, project decisions, and meeting notes session-to-session. No more re-pasting the same background every time. | | A developer or DevOps engineer | Notes that reference deprecated APIs or reversed architecture decisions get flagged before your AI cites them as current. |

---

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.

<details> <summary><strong>Lite and Full modes</strong></summary>

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.

</details> <details> <summary><strong>Alternative install methods (PyPI, pip, curl)</strong></summary>

# 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

</details>

---

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.

<details> <summary><strong>Technical pipeline</strong> (module by module)</summary>

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

</details>

---

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.

| Capability | Note apps | Basic RAG | NeuroStack | |-----------|-----------|-----------|------------| | Stores your notes | Yes | No | No (read-only by default; opt-in git-backed write tools) | | AI can search your notes | Some | Yes | Yes | | Detects stale/outdated notes | No | No | Yes | | AI memories persist across sessions | No | No | Yes | | Works with any MCP-compatible AI | No | Varies | Yes | | Tiered retrieval (saves 80-95% tokens) | No | No | Yes | | Profession-specific workflows | No | No | Yes | | Open source, self-hostable | Varies | Varies | Yes (Apache 2.0) |

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.

| Pack | Built for | |------|-----------| | researcher | Literature review, citation tracking, evolving arguments, stale paper detection | | writer | Character sheets, world-building, chapter outlines, continuity tracking | | student | Course notes, spaced repetition, exam prep, syllabus change detection | | developer | Code decisions, architecture notes, runbooks, deprecated API detection | | devops | Infrastructure runbooks, incident notes, change logs | | data-scientist | Experiment tracking, model notes, dataset documentation |

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.

| Level | Tokens | What your AI gets | |-------|--------|-------------------| | Quick facts | ~15 | Structured facts extracted from your notes: experiment-3 used learning-rate 0.001 | | Summaries | ~75 | AI-generated overview of a note | | Full content | ~300 | Actual Markdown content | | Auto (default) | Varies | Starts at quick facts, escalates only if the answer isn't there |

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 memorie