Neurostack

[](https://pypi.org/project/neurostack/) [](https://www.npmjs.com/package/neurostack) [](LICENSE) [](https://github.com/raphasouthall/neurostack/actions/workflows/ci.yml) [](https://modelcontextprotocol.io)

Not a note-taking app. A memory layer for the notes you already have.

Your AI assistant forgets everything when the conversation ends. You ask it about the paper you summarised last week — it has no idea. You ask it to continue the chapter outline you built together — it starts from scratch.

And even when it does find your notes, it might find the wrong version. The thesis argument you reversed, the runbook endpoint you deprecated, the decision you made in April that you overturned in June. It cites these confidently. It has no idea they're wrong.

NeuroStack reads your existing Markdown notes — from Obsidian, Logseq, Notion exports, or any folder of .md files — indexes them into a searchable knowledge graph, and connects that graph to your AI. It detects when notes have gone stale before your AI cites them. Indexing never modifies your files; optional MCP write tools let an AI client author or edit notes through your git history when you want it to.

npm install -g neurostack && neurostack init

Works with Claude, Cursor, Windsurf, Gemini CLI, VS Code, and Codex — anything 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: neurostack uninstall — your notes are 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. "We agreed in session 4 that Elena's backstory changes in act 2" — it remembers that. | | 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. 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.

Lite and Full modes

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

• Lite (~130 MB) — keyword search, link-based connections between notes, stale detection, MCP server. No GPU or Ollama required.
• Full (~560 MB) — adds semantic search (finds notes by meaning, not just keywords), 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

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 actually feels like

The researcher. You ask Claude to help write the methodology section. Instead of starting from scratch, it already knows you've read 50 papers on complementary learning systems, that you settled on a particular framing in January, and that the meta-analysis you were relying on has been flagged as stale — it keeps appearing in searches where it no longer fits. You check it, update the note, and the AI's next answer reflects where your thinking actually is.

The writer. You ask Cursor to help with chapter eleven. It knows Elena's backstory from chapter two, the decision you made in your world-building notes to keep magic systems implicit, and that you changed her last name in a revision three weeks ago. No contradictions.

The DevOps engineer. You ask about the deployment runbook for the auth service. NeuroStack surfaces it — but also flags it as stale. You check it. The endpoint was renamed six weeks ago. You fix the note. The next time anyone asks, they get the right answer.

The student. You're revising three weeks before exams. You ask your AI what's on the syllabus for Module 4. It searches your notes — and stale detection tells you two of the topics were in last year's module structure, which you replaced when the course was restructured. You know what to revise. You don't waste time on dropped content.

The data scientist. You ask about the hyperparameters from your best experiment. NeuroStack returns the results from the rerun, not the original — because you updated that note, and the update is reflected in the index.

---

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 feature no other tool offers. When a note keeps appearing in contexts where it no longer fits — a deprecated API, a reversed decision, a superseded paper — NeuroStack flags it and demotes it in future results. Without this, your AI confidently cites information that is no longer true.

---

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 can scan your past AI conversations, extract the key decisions, observations, and learnings, and save them as memories — automatically. No manual work.

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. Stale detection runs continuously. You don't maintain it — it maintains itself.

---

What changes day-to-day

| Without NeuroStack | With NeuroStack | |-------------------|-----------------| | AI answers from training data | AI answers from your actual notes | | Cites the runbook you deprecated | Flags it as stale, demotes it automatically | | No memory of yesterday's session | session_brief reconstructs working context | | Reading 10 notes to find one fact | Tiered retrieval: ~15 tokens for a structured fact | | Decisions lost after /clear | Typed memories persist indefinitely |

---

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 — 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///.md. NeuroStack only ever writes inside that one directory — your notes are never touched.
• 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).

---

All 24 MCP tools

Search & retrieval

| Tool | Description | |------|-------------| | vault_search | Hybrid search with tiered depth (triples, summaries, full, auto) | | vault_ask | RAG Q&A with inline citations | | vault_summary | Pre-computed note summary | | vault_graph | Wiki-link neighborhood with PageRank scores | | vault_related | Semantically similar notes by embedding distance | | vault_triples | Knowledge graph facts (subject-predicate-object) | | vault_communities | GraphRAG queries across topic clusters | | vault_context | Task-scoped context assembly within token budget |

Context & insights

| Tool | Description | |------|-------------| | session_brief | Compact session briefing | | vault_stats | Index health, excitability breakdown, memory stats | | vault_record_usage | Track note hotness | | vault_prediction_errors | Surface stale notes |

Memories

| Tool | Description | |------|-------------| | vault_remember | Store a memory (returns duplicate warnings + tag suggestions) | | vault_update_memory | Update a memory in place | | vault_merge | Merge two memories (unions tags, audit trail) | | vault_forget | Delete a memory | | vault_memories | List or search memories | | vault_harvest | Extract insights from session transcripts |

Sessions

| Tool | Description | |------|-------------| | vault_session_start | Begin a memory session | | vault_session_end | End session with optional summary and auto-harvest |

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

| Tool | Description | |------|-------------| | vault_read_file | Read a .md file under your vault root | | vault_list_files | List .md files; hidden segments (.git, .obsidian, …) always excluded | | vault_write_file | Create or overwrite a .md file; commits + pushes `ori

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: raphasouthall
• Source: raphasouthall/neurostack
• License: Apache-2.0
• Homepage: https://neurostack.sh

Install and usage instructions live in the source repository linked above.