nous

Your project's brain. One command to set up. Zero config to start.

npx nousdb init --hook

That's it. Your AI assistant now has a persistent memory for this project — it learns from your conversations and remembers how things work.

---

What is this?

Every project has knowledge that lives in developers' heads: how the payment flow works, why we chose Redis over Memcached, the rule about never pushing to main. This knowledge gets lost between sessions, forgotten by new team members, and never reaches your AI tools.

nous fixes that. It's a single SQLite file (.nous/knowledge.db) that stores your project's knowledge and makes it queryable by any AI via MCP.

30-second setup

cd your-project
npx nousdb init --hook

This creates:

.nous/knowledge.db        ← the brain (commit to git, share with team)
.claude/settings.json     ← Claude Code connects automatically

Done. Just start Claude Code normally — nous is already connected. No server to run, no extra terminal.

Without --hook, you get query-only (no auto-learning). Without Claude Code, you can still use the CLI to teach and search.

How it works

Your AI can query the brain

After init, Claude Code has 10 MCP tools available. The most useful:

You: "I need to add retry logic to the payment flow"

Claude Code calls nous_context("add retry logic to payment flow")
  → returns relevant concepts, decisions, and patterns
  → Claude now knows how payments work before writing a single line

Your conversations teach the brain

With --hook, nous listens to every conversation (async, non-blocking):

You: "We decided to use Redis for caching because we need pub/sub"
Claude: [implements the feature]

                    ↓ Stop hook fires (background)
                    ↓ reads conversation transcript
                    ↓ heuristic classifier detects "we decided to..."
                    ↓ saves as decision with confidence: 0.6

Next session:
You: "How does caching work?"
Claude Code calls nous_query("caching")
  → "We decided to use Redis for caching because we need pub/sub"

No manual effort. You just have conversations and the brain learns.

You can teach it directly

# How something works
npx nousdb teach concept "Payment Flow" \
  "Stripe webhooks hit PaymentController, which dispatches to OrderService"

# Why a decision was made
npx nousdb teach decision "Chose SQLite" \
  "Portability over scale — the brain file lives in git"

# Rules to follow
npx nousdb teach pattern "API Responses" \
  "Always use ApiResponse wrapper, never return raw arrays"

Three knowledge types

Type	When to use	Signals
concept	How something works	"works by", "the flow is", "responsible for"
decision	Why something was chosen	"we decided", "opted for", "instead of"
pattern	Rules to follow	"always", "never", "make sure", "convention"

Search

npx nousdb ask "payment"

nous uses hybrid search: FTS5 keyword matching + vector semantic search (OpenAI embeddings) + Reciprocal Rank Fusion to merge results. Entries found by both methods get boosted.

Works without an API key too — falls back to keyword search only.

Semantic search (optional)

For semantic search ("how do we process charges" finds "Payment Flow"), set your OpenAI key:

export OPENAI_API_KEY=sk-...

Without it, everything works — you just get keyword matching instead of semantic.

Sharing with your team

The .nous/knowledge.db file is designed to be committed to git:

• init adds merge=binary to .gitattributes automatically
• No WAL sidecar files (journal mode = DELETE)
• ~2.5MB per 1,000 entries
• Every team member and every AI tool gets the same project knowledge

MCP tools

After init, Claude Code (or any MCP client) gets these tools:

Tool	What it does
nous_query	Search the brain (hybrid keyword + semantic)
nous_teach	Add new knowledge
nous_recall	Get entry by ID or exact title
nous_update	Update existing entry
nous_relate	Create/query relationships between entries
nous_forget	Deprecate or delete entries
nous_context	Get all relevant knowledge for a task description
nous_extract	Extract knowledge from a block of text
nous_recent	Recently added/modified entries
nous_status	Brain stats and health

Manual MCP setup (if not using init)

claude mcp add nous -- npx nousdb serve

You never need to run nous serve yourself. Claude Code starts it automatically in the background via the config in .claude/settings.json.

CLI reference

npx nousdb init                             # Interactive setup wizard
npx nousdb init --import --hook             # Non-interactive, all features
npx nousdb status                           # Brain statistics
npx nousdb teach <type> <title> <content>   # Add knowledge
npx nousdb ask <question>                   # Search the brain
npx nousdb import [file]                    # Import from CLAUDE.md, README, ADRs
npx nousdb viz                              # Open brain visualization in browser
npx nousdb export [--format json|markdown]  # Export for backup or docs
npx nousdb extract --stdin [--auto-save]    # Extract knowledge from piped text

How auto-learning works

When you run init --hook, nous installs a Stop hook in Claude Code:

1. After every Claude response, the hook fires (async, non-blocking)
2. It reads the conversation transcript (transcript_path JSONL)
3. A heuristic classifier scans for decision/concept/pattern signals
4. New knowledge is saved with confidence: 0.6 and source: extracted
5. Deduplication prevents the same knowledge from being stored twice

The classifier uses ~30 regex patterns (no LLM calls, zero cost, <10ms). It's intentionally conservative — better to miss knowledge than add noise. You can always teach it directly.

What gets created

your-project/
├── .nous/
│   ├── knowledge.db      ← the brain (commit this)
│   ├── config.json       ← settings + API key (commit this)
│   └── .gitignore        ← excludes WAL/journal files
├── .claude/
│   ├── settings.json     ← Claude Code auto-connects (no manual server needed)
│   └── hooks/
│       └── nous-extract.sh  ← auto-learning script (with --hook)
└── .gitattributes        ← binary merge strategy for .db

License

MIT