Local-first · Any AI provider · Apache-2.0

Your second brain, starting today

Install one command, answer a few questions, and you have a knowledge vault that gets smarter every day you use it. NeuroStack scaffolds your vault, indexes everything by meaning, surfaces what needs attention, and gives any AI tool long-term memory—all running locally.

Get startedSee features
Zero prerequisitesAny AI provider21 MCP tools~15 tok per triple
01

How It Works

1

Install & Init

One command installs everything—no Python, git, or curl needed. The interactive setup walks you through vault location, model selection, and optional profession packs.

npm install -g neurostack neurostack init
2

Connect any AI

Use as an MCP server with Claude Code, Codex, Gemini CLI, Cursor, Windsurf—or pipe CLI output into any LLM workflow.

neurostack serve
3

It gets better every day

Hot notes surface what matters. Drift detection flags what's stale. Community detection reveals hidden themes. Your vault becomes a living knowledge system that improves the more you use it.

neurostack search "query"
02

Features

Search

Hybrid Search

Combines FTS5 full-text with semantic embeddings for meaning-based retrieval. Keyword, semantic, or hybrid modes.

McClelland et al. 1995 — Complementary learning systems
Efficiency

Tiered Retrieval

Triples (~15 tok) → Summaries (~75 tok) → Full content. Auto-escalates based on result quality. Token-efficient by design.

CLS theory — hippocampal rapid binding
Neuroscience

Hot Notes

Active notes attract preferential connections — inspired by CREB-mediated neuronal excitability windows in memory consolidation.

Han et al. 2007 — Science 316(5823)
Quality

Drift Detection

Flags notes retrieved with high cosine distance from query intent. Surfaces outdated content and miscategorisation.

Sinclair & Bhatt 2022 — PNAS 119(31)
Graph

Community Detection

Attractor basin community detection with hierarchical levels. Inspired by Hopfield network energy landscapes. Coarse thematic clusters and fine sub-themes with LLM-generated summaries.

Ramsauer et al. 2020 — Hopfield Networks is All You Need
Synthesis

GraphRAG Queries

Answer thematic questions across the vault using map-reduce over community summaries. Global reasoning, not just retrieval.

Engram connectivity — Josselyn & Tonegawa 2020
Context

Session Briefs

Auto-generated ~500-token context combining vault changes, git commits, top connected notes, and time context.

Contextual reinstatement theory
Knowledge

SPO Triples

Structured Subject-Predicate-Object facts extracted from notes. Efficient factual lookup at ~10-20 tokens per triple.

Semantic memory organisation
Protocol

MCP Server

21-tool Model Context Protocol server. Works with Claude Code, Codex, Gemini CLI, Cursor, Windsurf - any MCP-compatible client. Provider-agnostic by design.

Standard transport: stdio, SSE, or HTTP
Memory

Agent Memory Layer

AI agents write observations, decisions, conventions, learnings, context, and bugs into the vault via vault_remember / vault_forget / vault_memories. Memories have optional TTL, workspace scoping, and surface automatically in search results.

Episodic memory encoding — Tulving 1972
Scoping

Workspace Scoping

Scope search and memory to subdirectories with --workspace flag or NEUROSTACK_WORKSPACE env var. Keeps project context isolated without separate databases.

Contextual binding - Howard & Kahana 2002
Lifecycle

Session Tracking

Track AI coding sessions with start/end lifecycle hooks. Sessions group memories, enable summaries, and auto-clean orphaned sessions after crashes.

Episodic boundary detection - Zacks et al. 2007
Extraction

LLM-Assisted Harvest

Two-tier insight extraction from session transcripts. Broad regex pre-filter selects candidates, then local LLM classifies and summarizes. Supports Claude Code, VS Code Chat, Codex CLI, Aider, and Gemini CLI session transcripts. Falls back to regex-only if Ollama is unavailable.

Consolidation during offline periods - Diekelmann & Born 2010
03

Neuroscience Grounding

Every core feature maps to established memory neuroscience research. This is not metaphor — the algorithms are direct computational analogues of biological memory mechanisms.

FeatureNeuroscience ConceptMechanismKey Paper
Hot NotesCREB-mediated excitability windowsActive notes attract preferential connections, mirroring how elevated CREB levels bias neuronal recruitment into engramsHan et al. 2007, Science 316(5823), 457-460
Drift DetectionPrediction error-driven reconsolidationNotes surfacing in unexpected contexts trigger review, analogous to prediction errors destabilising consolidated memoriesSinclair & Bhatt 2022, PNAS 119(31)
Knowledge GraphEngram connectivity networksWiki-links + PageRank model the interconnected neural ensembles that constitute distributed memory tracesJosselyn & Tonegawa 2020, Science 367(6473)
CommunitiesHopfield attractor basinsAttractor basin community detection mirrors how memories settle into energy minima in Hopfield networksRamsauer et al. 2020, ICLR
Tiered RetrievalComplementary learning systemsProgressive depth escalation models the hippocampal-neocortical memory consolidation pathwayMcClelland et al. 1995, Psych. Review 102(3)
Hot Notes

CREB-mediated excitability windows

Active notes attract preferential connections, mirroring how elevated CREB levels bias neuronal recruitment into engrams

Han et al. 2007, Science 316(5823), 457-460
Drift Detection

Prediction error-driven reconsolidation

Notes surfacing in unexpected contexts trigger review, analogous to prediction errors destabilising consolidated memories

Sinclair & Bhatt 2022, PNAS 119(31)
Knowledge Graph

Engram connectivity networks

Wiki-links + PageRank model the interconnected neural ensembles that constitute distributed memory traces

Josselyn & Tonegawa 2020, Science 367(6473)
Communities

Hopfield attractor basins

Attractor basin community detection mirrors how memories settle into energy minima in Hopfield networks

Ramsauer et al. 2020, ICLR
Tiered Retrieval

Complementary learning systems

Progressive depth escalation models the hippocampal-neocortical memory consolidation pathway

McClelland et al. 1995, Psych. Review 102(3)
04

CLI Reference

Core
neurostack init
Interactive setup wizard — vault location, mode selection (local/cloud), model choice, and profession packs. Or: neurostack init [path] --mode full --cloud
neurostack index
Full re-index of vault — parses notes, extracts chunks, builds FTS5 and embeddings
neurostack watch
Watch vault for changes and live-index on save
neurostack status
Overview of index health and configuration
neurostack doctor
Validate all subsystems — SQLite, Ollama, models, schema version
neurostack stats
Index statistics: notes, chunks, embeddings, summaries, triples, communities
neurostack uninstall
Complete removal — data, venv, database, and npm package
Search & Retrieval
neurostack search "query"
Hybrid FTS5 + semantic search. Flags: --top-k, --mode [hybrid|semantic|keyword], --context, --rerank, --workspace, --json
neurostack tiered "query"
Tiered search with auto-escalation. Flags: --depth [triples|summaries|full|auto], --top-k, --context, --rerank, --json
neurostack triples "query"
Search structured SPO facts. Flags: --top-k, --mode, --json
neurostack summary <path>
Get pre-computed 2-3 sentence note summary (~100-200 tokens)
Graph & Communities
neurostack graph <note.md>
Wiki-link neighbourhood with PageRank scoring. Flag: --depth
neurostack communities build
Run Leiden clustering + generate LLM summaries for each community
neurostack communities query "q"
Global GraphRAG query over communities. Flags: --top-k, --level [0|1], --no-map-reduce, --json
neurostack communities list
List detected communities. Flag: --level
Maintenance
neurostack prediction-errors
Show poorly-fit notes. Flags: --type [low_overlap|contextual_mismatch], --limit, --resolve <path>
neurostack backfill [target]
Backfill missing summaries, triples, or all
neurostack reembed-chunks
Re-embed all chunks with updated context
neurostack folder-summaries
Build folder-level summaries for semantic context boosting. Flag: --force
Vault & Memories
neurostack scaffold --list
List available profession packs (researcher, developer, writer, student, devops, data-scientist)
neurostack onboard <dir>
Onboard an existing directory of notes into a NeuroStack vault. Flag: -n (dry run)
neurostack memories add "text"
Store an agent memory. Flags: --type [observation|decision|convention|learning|context|bug], --ttl
neurostack memories list
List all stored memories
neurostack memories search "q"
Search memories by keyword
neurostack record-usage <path>
Mark a note as used — drives hotness scoring for retrieval priority
Server & Sessions
neurostack serve
Start MCP server. Flag: --transport [stdio|sse]
neurostack api
Start OpenAI-compatible HTTP API on https://neurostack.sh
neurostack setup-client <name>
Auto-configure AI client — cursor, windsurf, gemini, vscode, claude-code
neurostack sessions start
Start a new memory session. Flags: --source, --workspace
neurostack sessions end <id>
End a session. Flags: --summarize (LLM summary), --no-harvest (skip auto-harvest)
neurostack sessions list
List recent sessions with status and memory counts
neurostack sessions show <id>
Show session details and associated memories
neurostack sessions search "q"
Search session transcripts via FTS5
neurostack harvest
Extract insights from recent sessions using two-tier regex + LLM classification. Flags: --sessions N, --dry-run
neurostack brief
Generate a compact ~500-token session context brief
See it in action
NeuroStack Search
05

MCP Server Tools

NeuroStack exposes a Model Context Protocol server with 21 tools. Works with Claude Code, Codex, Gemini CLI, Cursor, Windsurf, and any MCP-compatible client.

vault_search+

Primary retrieval tool — hybrid FTS5 + semantic search with tiered depth escalation. Start with depth="auto" and let it escalate based on coverage.

Parameters

querystrNatural language search query (required)
top_kintNumber of results. Default: 5
modestr"hybrid" | "semantic" | "keyword". Default: "hybrid"
depthstr"triples" | "summaries" | "full" | "auto". Default: "auto"
contextstrDomain context for boosting (e.g. "neuroscience", "devops")
workspacestrScope to subdirectory (e.g. "work/project-x"). Also via NEUROSTACK_WORKSPACE env var
Most lookups — specific facts, notes, or topics. Always pass depth="auto" and context for best results.
vault_summary+

Get a pre-computed 2-3 sentence summary of a note (~100-200 tokens vs ~500-2000 for full file). Quick overview before committing to a full read.

Parameters

path_or_querystrNote path ("research/predictive-coding.md") or search query (required)
Quick overview of a note before deciding whether to read the full content.
vault_graph+

Wiki-link neighbourhood with PageRank scoring. Discover related notes without manually following links.

Parameters

notestrNote path (required)
depthintLink-hop distance. Default: 1
Exploring what connects to a specific note — hub discovery, dependency mapping.
vault_triples+

Search structured Subject-Predicate-Object facts at ~10-20 tokens each. The most token-efficient retrieval method.

Parameters

querystrNatural language query (required)
top_kintNumber of triples. Default: 10
modestr"hybrid" | "semantic" | "keyword". Default: "hybrid"
Efficient factual lookup — "what depends on X?", "where does Y run?"
vault_communities+

GraphRAG global queries over Leiden community summaries. Uses map-reduce synthesis for thematic questions that span the whole vault.

Parameters

querystrThematic question (required)
top_kintCommunities to retrieve. Default: 6
levelint0 = coarse themes, 1 = fine sub-themes. Default: 0
map_reduceboolLLM synthesis vs raw hits. Default: true
Thematic questions — "what topics dominate?", "how does X relate across the vault?"
vault_stats+

Index health metrics — coverage statistics for notes, chunks, embeddings, summaries, graph edges, triples, and communities.

Monitor indexing progress and identify coverage gaps.
vault_record_usage+

Track note access for hotness scoring. Notes that get used more often rank higher in future searches.

Parameters

note_pathslist[str]Notes that were actually consumed (required)
Provide relevance feedback to improve future ranking.
vault_prediction_errors+

Surface notes with retrieval anomalies — drift detection. Flags outdated content or notes appearing in unexpected contexts.

Parameters

error_typestr"low_overlap" or "contextual_mismatch" (optional)
limitintMax results. Default: 20
resolvelist[str]Mark specific notes as resolved (optional)
Find outdated or miscategorised notes that need attention.
vault_remember+

Write an observation, decision, convention, learning, context note, or bug into the vault. Memories surface automatically in future search results.

Parameters

contentstrThe memory content to store (required)
categorystr"observation" | "decision" | "convention" | "learning" | "context" | "bug". Default: "observation"
ttl_daysintAuto-expire after N days (optional, omit for permanent)
workspacestrScope to a subdirectory (optional)
Agents recording what they learn — project conventions, debugging insights, architectural decisions.
vault_forget+

Remove a previously stored memory by ID. Use when a memory is outdated, incorrect, or no longer relevant.

Parameters

memory_idstrThe memory ID to remove (required)
Cleaning up stale or superseded agent memories.
vault_memories+

List stored agent memories, optionally filtered by category or workspace. Memories are returned with their IDs for management.

Parameters

categorystrFilter by category (optional)
workspacestrFilter by workspace scope (optional)
limitintMax results. Default: 20
Reviewing what an agent has remembered — auditing conventions, checking for stale context.
vault_session_start+

Start a new memory session. Sessions group memories and enable lifecycle tracking with auto-harvest on end.

Parameters

source_agentstrAgent identifier (e.g. "claude-code"). Optional
workspacestrWorking directory scope. Optional
Called at the start of an AI coding session to begin tracking memories and insights.
vault_session_end+

End a memory session. Optionally generates an LLM summary of session memories and auto-harvests insights from the transcript.

Parameters

session_idintSession ID to end (required)
summarizeboolGenerate LLM summary of session memories. Default: false
Called at session end to close lifecycle, summarize work, and harvest insights.
session_brief+

Compact ~500-token session context combining recent vault changes, git commits, external memories, top connected notes, and time context.

Lightweight context injection at session start - get up to speed fast.
vault_ask+

RAG Q&A with inline [[citations]]. Ask natural language questions, get answers grounded in vault content.

Parameters

questionstrNatural language question (required)
Get a cited answer to a question using vault content as source material.
vault_related+

Find semantically similar notes by embedding distance. Discover notes you didn't know were connected.

Parameters

notestrNote path to find related notes for (required)
Exploring semantic neighbours — finding unexpected connections between notes.
vault_context+

Task-scoped context assembly within a token budget. Recovers working context after /clear or new conversation.

Parameters

querystrTask description for context assembly (required)
Rebuilding working context after a conversation reset or starting a new session.
vault_capture+

Quick-capture thoughts to vault inbox. Zero-friction note creation without leaving the AI session.

Parameters

contentstrNote content to capture (required)
Jotting down ideas, todos, or fleeting thoughts during a coding session.
vault_update_memory+

Update an existing memory in place. Modify content, tags, or category without delete+recreate.

Parameters

memory_idstrThe memory ID to update (required)
contentstrUpdated memory content (optional)
categorystrUpdated category (optional)
Refining or correcting an existing memory without losing its history.
vault_merge+

Merge two memories with tag union and audit trail. Deduplicate while preserving provenance.

Parameters

source_idstrMemory to merge from (required)
target_idstrMemory to merge into (required)
Consolidating duplicate or overlapping memories into a single authoritative record.
vault_harvest+

Extract insights from AI coding session transcripts. Two-tier regex + LLM classification pipeline.

Parameters

sessionsintNumber of recent sessions to harvest. Default: 5
dry_runboolPreview without saving. Default: false
Mining past coding sessions for decisions, conventions, and learnings worth remembering.
06

Get Started

Run neurostack init to choose your mode, vault location, and set up Ollama models. It auto-installs Ollama if needed and skips models you already have. Re-run anytime to upgrade.

Lite Mode

~130MB

FTS5 keyword search, wiki-link graph, stale note detection, and MCP server. No GPU needed.

# Bootstrap + choose lite mode npm install -g neurostack neurostack init --mode lite
  • FTS5 full-text search
  • Wiki-link graph + PageRank
  • Stale note detection
  • File watching + live indexing
  • MCP server (stdio/SSE)
  • Interactive setup wizard

What gets installed

  • uv ~30MB — Python package manager (auto-installed)
  • Python 3.12 ~50MB — standalone, managed by uv
  • NeuroStack + deps ~50MB — pyyaml, watchdog, mcp, httpx
  • Config — ~/.config/neurostack/config.toml
  • Database — ~/.local/share/neurostack/neurostack.db

Full Mode

~210MB

Adds semantic embeddings, LLM summaries, triple extraction, and Hopfield-grounded ranking. Requires Ollama.

# Full mode + pull Ollama models npm install -g neurostack neurostack init --mode full
  • Everything in Lite, plus:
  • Semantic embedding search (768-dim)
  • LLM-generated note summaries
  • SPO triple extraction
  • Hopfield-grounded ranking

What gets installed

  • NeuroStack + deps ~80MB — pyyaml, watchdog, mcp, httpx, numpy

Additional installs

Cloud Mode

~130MB

Zero GPU required. Install in lite mode, log in via browser, push your vault for server-side Gemini-powered indexing. Full semantic search without local ML.

# Cloud mode npm install -g neurostack neurostack init --cloud neurostack cloud push
  • No GPU or Ollama required
  • Gemini-powered embeddings + summaries + triples
  • Browser login (Google OAuth)
  • Dashboard at app.neurostack.sh
  • Free tier: 500 notes, 1,000 queries/mo

Community mode: Add topic cluster detection with neurostack init --mode community (+15MB, leidenalg GPL-3.0).

Upgrade anytime: Re-run neurostack init to switch modes (e.g., lite → full). Uninstall: neurostack uninstall removes everything. Config is preserved so reinstall picks up where you left off.

07

NeuroStack Cloud

Skip local GPU setup. NeuroStack Cloud indexes your vault server-side with Google Gemini — embeddings, summaries, and triples generated in minutes. Your local CLI and MCP server work the same, backed by the cloud-indexed database.

Cloud Onboarding

~130MB

Install in lite mode, log in via browser, push your vault for server-side indexing, then pull the indexed database.

# 1. Install + choose cloud npm install -g neurostack neurostack init --cloud ~/brain # 2. Push vault for indexing neurostack cloud push # 3. Pull indexed database neurostack cloud pull # 4. Search via cloud API neurostack cloud query "your question"
  • No GPU or Ollama required
  • Gemini-powered embeddings + summaries + triples
  • Browser login (Google OAuth)
  • Dashboard at app.neurostack.sh
  • Free tier: 500 notes, 1,000 queries/mo

Cloud Dashboard

app.neurostack.sh

Manage your vault, API keys, usage, and billing from the web dashboard.

  • Vault stats and health overview
  • Query playground with depth selector
  • API key management (create / revoke)
  • Usage tracking with progress bars
  • Stripe billing (upgrade / manage)
  • Account export and deletion

Tiers

  • Free — 500 notes, 1,000 queries/mo, 100 index jobs/mo
  • Pro — 25,000 notes, 100,000 queries/mo, 2,000 index jobs/mo — $9/mo
  • Team — 100,000 notes, 500,000 queries/mo, 10,000 index jobs/mo — $29/mo
08

Connect Your AI

NeuroStack works with any MCP-compatible client. Use the local MCP server for full-featured access, or the cloud endpoint for browser-based tools.

Claude Desktop

Local

Auto-configure Claude Desktop with a single command. All 21 MCP tools available locally via stdio transport.

# Auto-detect platform + merge config neurostack setup-desktop

Or manually add to your Claude Desktop config:

{ "mcpServers": { "neurostack": { "command": "neurostack", "args": ["serve"], "env": {} } } }
  • All 21 MCP tools (search, graph, memories, sessions)
  • Works on macOS, Windows, and Linux
  • Restart Claude Desktop to activate

Claude.ai (Browser)

Cloud

Connect NeuroStack directly to Claude.ai in your browser via the remote MCP endpoint. No local install required — just a NeuroStack Cloud account.

# Remote MCP endpoint https://mcp.neurostack.sh/mcp

Setup steps

  • 1. Create an account at app.neurostack.sh
  • 2. Push your vault: neurostack cloud push
  • 3. In Claude.ai, go to Settings → Integrations → Add MCP Server
  • 4. Enter the URL: https://mcp.neurostack.sh/mcp
  • 5. Complete Google sign-in when prompted
  • 4 cloud tools: search, triples, summary, stats
  • OAuth 2.1 authentication (Google sign-in)
  • No local install needed for browser use
  • Free tier: 500 notes, 1,000 queries/mo

Claude Code

Local

Auto-configure Claude Code for local MCP access.

neurostack setup-client claude-code
  • All 21 MCP tools in your terminal
  • Writes to ~/.claude/.mcp.json
  • Restart Claude Code to activate

Other Clients

Local

One-command setup for Cursor, Windsurf, VS Code, and Gemini CLI.

# Pick your client neurostack setup-client cursor neurostack setup-client windsurf neurostack setup-client vscode neurostack setup-client gemini

Any MCP-compatible client can also use the remote endpoint at https://mcp.neurostack.sh/mcp with OAuth authentication.

09

Comparison

NeuroStack complements Obsidian as your editor — it adds the AI search engine layer that Obsidian lacks.

FeatureNeuroStackObsidianKhojNotion AI
Full ~210MBLite ~130MB
Local-firstYesYesYesPartialNo
AI-provider agnosticMCPMCPNoPartialNo
Full-text searchFTS5FTS5YesYesYes
Semantic searchHybridNoPluginYesYes
Knowledge graphPageRankPageRankBacklinksNoNo
Community detectionAttractor basinNoNoNoNo
Drift detectionYesYesNoNoNo
Tiered retrievalAutoNoNoNoNo
AI summaries & triplesYesNoNoPartialYes
Hopfield rankingYesNoNoNoNo
CLIYesYesNoYesNo
MCP serverYesYesNoNoNo
Agent memoryYesYesNoNoNo
Session lifecycleYesYesNoNoNo
LLM harvestYesNoNoNoNo
Open sourceApache-2.0Apache-2.0Core onlyYesNo
GPU requiredOptionalNoNoOptionalNo
PriceFreeFree$50/yrFree/paid$10/mo
10

Configuration

~/.config/neurostack/config.toml
vault_root = "~/brain" db_dir = "~/.local/share/neurostack" # Ollama endpoints embed_url = "https://neurostack.sh" embed_model = "nomic-embed-text" embed_dim = 768 llm_url = "https://neurostack.sh" llm_model = "phi3.5" # Session transcripts session_dir = "~/.claude/projects"
MCP Client Setup
# Auto-configure any supported client neurostack setup-desktop neurostack setup-client claude-code neurostack setup-client cursor neurostack setup-client windsurf neurostack setup-client vscode neurostack setup-client gemini # See Connect Your AI for full details

Environment Variable Overrides

All config values support NEUROSTACK_* env var overrides:

NEUROSTACK_VAULT_ROOTNEUROSTACK_DB_DIRNEUROSTACK_EMBED_URLNEUROSTACK_EMBED_MODELNEUROSTACK_EMBED_DIMNEUROSTACK_LLM_URLNEUROSTACK_LLM_MODELNEUROSTACK_SESSION_DIRNEUROSTACK_WORKSPACE