Your notes are lying to you. That runbook from last quarter? It references an API endpoint you deprecated in February. The architecture decision record your AI just cited? It was reversed two sprints ago. Every knowledge base decays -- and AI agents that search it will confidently repeat whatever they find.1

NeuroStack is the memory layer that fights this. It indexes your Markdown vault into a knowledge graph, detects stale notes before your AI cites them, and tiers retrieval so simple queries cost ~15 tokens instead of ~300. It persists agent memories across sessions, tracks what you actually use, and surfaces what's gone stale. Your vault files are never modified.

Built for DevOps/SRE teams and infrastructure engineers who maintain runbooks, incident reports, architecture docs, and operational playbooks -- the kind of knowledge that changes fast and hurts when it's wrong.

Works with Claude Code, Cursor, Windsurf, Codex, and Gemini CLI via MCP.

1 Prediction error signals -- when retrieved content diverges from query context -- trigger reconsolidation in biological memory (Sinclair & Bhatt 2022). NeuroStack applies the same principle: notes that keep appearing where they don't belong are flagged and demoted.

Get started

npm install -g neurostack
neurostack init

The wizard walks you through everything: cloud or local, lite or full, Ollama models, vault path, profession pack, and full indexing -- one command.

| | Cloud | Local | |--|-------|-------| | Best for | Zero friction, any machine | Privacy-first, offline, power users | | Indexing | Gemini API (server-side) | Ollama on your machine | | Search | Local SQLite | Local SQLite (same DB) | | GPU required | No | Recommended for Full mode | | Multi-device | Push once, pull anywhere | Manual DB sync | | Cost | Free tier / Pro plans | Free (your hardware) |

Cloud

No GPU, no Ollama, no ML dependencies. Gemini indexes your vault server-side and returns a ready-to-use SQLite database. All search runs locally against that DB.

neurostack init     # choose "Cloud" → vault setup → login → push

Free tier: 500 queries/month, 200 notes. Dashboard: app.neurostack.sh

Privacy notice: Cloud mode requires explicit consent before uploading. Your vault files are sent to Google's Gemini API for indexing (embeddings, summaries, knowledge graph triples). Files are processed via HTTPS and not retained after indexing completes. Run neurostack cloud consent to review and grant consent. You can exclude sensitive files with a .neurostackignore file (gitignore syntax).

Local

Run everything on your machine with Ollama. Choose a tier during neurostack init:

Lite (~130 MB) -- FTS5 search, wiki-link graph, stale detection, MCP server. No GPU or Ollama required.
Full (~560 MB) -- adds semantic search, AI summaries, knowledge graph triples, and attractor basin community detection via local Ollama. GPU or 6+ core CPU recommended.

Full mode automatically runs the complete indexing pipeline: embeddings, summaries, triples, and community detection.

Non-interactive mode:

neurostack init --mode full --pull-models ~/brain
neurostack init --cloud ~/brain

<details> <summary>Alternative install methods</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+, Fedora 38+, bare pip install outside a venv is blocked by PEP 668. Use npm, pipx, or uv tool install.

</details>

To uninstall: neurostack uninstall

Connect to your AI

Claude Code (one command)

claude mcp add neurostack -- neurostack serve

Claude Desktop

Download the .mcpb bundle from Releases and double-click to install. Or auto-configure:

neurostack setup-desktop

Remote MCP (no local install)

Connect Claude to your vault via NeuroStack Cloud -- no Python, no Ollama, nothing to install locally:

claude mcp add neurostack --transport http https://mcp.neurostack.sh/mcp

Other MCP clients

Auto-configure Cursor, Windsurf, Gemini CLI, VS Code, or Codex:

neurostack setup-client cursor      # or: windsurf, gemini, vscode, claude-code
neurostack setup-client --list      # show all supported clients

<details> <summary>Manual JSON config</summary>

Add to your client's MCP config file:

{
  "mcpServers": {
    "neurostack": {
      "command": "neurostack",
      "args": ["serve"],
      "env": {}
    }
  }
}

</details>

After connecting, all 21 MCP tools are available. Search your vault, save memories, detect stale notes -- all from your AI chat.

Search

Retrieval is tiered. Most queries resolve at the cheapest tier:

| Tier | Tokens | What your AI gets | Example | |------|--------|-------------------|---------| | Triples | ~15 | Structured facts: Alpha API -> uses -> PostgreSQL 16 | Quick lookups, factual questions | | Summaries | ~75 | AI-generated note summary | "What is this project about?" | | Full content | ~300 | Actual Markdown content | Deep dives, editing context | | Auto | Varies | Starts at triples, escalates only if coverage is low | Default for most queries |

Full mode adds hybrid semantic + keyword search with neuroscience-grounded ranking: energy landscape convergence, lateral inhibition, and prediction error feedback. Workspace scoping restricts queries to a vault subdirectory.

neurostack search "k8s pod eviction policy"
neurostack tiered "incident response runbook" --top-k 3
neurostack search -w "work/infra" "terraform state migration"
neurostack --json search "query" | jq      # machine-readable output

Maintain

Stale note detection. When a note keeps appearing in search contexts where it doesn't belong, NeuroStack flags it as a prediction error. Old decisions, superseded specs, reversed conclusions -- without detection, your AI cites these confidently. Notes with unresolved prediction errors are automatically demoted in future search results.

Excitability decay. Recently accessed notes score higher in search results. Unused notes fade over time. Modeled on CREB-regulated neuronal excitability (Han et al. 2007).

Co-occurrence learning. Notes retrieved together frequently get their connection weights strengthened automatically. The search graph learns your actual workflow, not just your file structure.

Topic clusters. Attractor basin community detection groups notes into thematic clusters for broad "what do I know about X?" queries. Uses Hopfield-style dynamics with a blended similarity matrix (embeddings + co-occurrence + wiki-links). Included in Full mode -- no extra dependencies.

Lateral inhibition. Higher-ranked search results suppress semantically similar competitors, promoting diversity. Prevents five near-identical notes from dominating your results.

neurostack prediction-errors             # stale note detection
neurostack decay                         # excitability report
neurostack communities build             # rebuild topic clusters
neurostack watch                         # auto-index on vault changes

Agent memories

AI assistants can write typed memories back to NeuroStack: observation, decision, convention, learning, context, bug. Memories are stored in SQLite and surfaced automatically in vault_search results.

Near-duplicate detection with merge support
Optional TTL for ephemeral memories
Tag suggestions on save
Update in place or merge two memories with audit trail

neurostack memories add "postgres 16 requires --wal-level=replica for logical replication" --type decision --tags "db,postgres"
neurostack memories search "postgres replication"
neurostack memories merge <target> <source>
neurostack memories prune --expired

Session harvest

Scans Claude Code JSONL session transcripts, extracts insights (observations, decisions, conventions, bugs), and deduplicates against existing memories before saving.

neurostack harvest --sessions 5          # extract from last 5 sessions
neurostack hooks install                 # install systemd timer for hourly harvest
neurostack sessions search "query"       # search raw transcripts

Context recovery

Two modes for rebuilding working context after /clear or starting a new session:

vault_context -- task-anchored. Assembles relevant notes, memories, and triples for a specific task within a token budget.
session_brief -- time-anchored. Compact briefing of recent activity, hot notes, and alerts.

neurostack context "migrate auth service to OIDC" --budget 2000
neurostack brief

Build

NeuroStack scaffolds new vaults or onboards existing Markdown directories. Six profession packs provide domain-specific templates, seed notes, and workflow guidance.

neurostack init                        # interactive setup, offers profession packs
neurostack onboard ~/my-notes          # import existing notes with frontmatter generation
neurostack scaffold devops             # apply a pack to

Neurostack

Install / Use

README