🪻 NotNessie

Project memory for Claude Code, stored on your own machine. NotNessie remembers a repo's decisions, constraints, preferences, verified commands, open questions, and bug notes across sessions — so Claude Code stops re-learning your project from scratch every single time.

📚 Full documentation lives at grexlin85.github.io/notnessie. This README is the tour; the docs site is the reference.

---

The problem

Every Claude Code session starts cold. You explain that the project uses Fastify and not Express, that tests run with pnpm test auth, that the public API response shape is frozen, that nobody touches the generated Prisma files. Claude does great work — and then the session ends and all of that context evaporates. Next task, you say it all again.

CLAUDE.md helps, but it's a single hand-maintained file. It doesn't grow on its own, it doesn't rank what's relevant to the task at hand, and it has no idea which command you verified last Tuesday.

NotNessie is the missing layer. It captures the durable facts from your Claude Code work — decisions, rules, preferences, commands that actually worked, questions left open — and serves them back as a compact, task-aware context pack the next time you sit down. The memory lives in your Postgres. No account, no cloud, nothing leaves your machine.

How it plugs into Claude Code

NotNessie integrates three ways, and notnessie init wires up all of them:

1. An MCP server (.mcp.json) exposing nine memory tools Claude can call mid-task — retrieve context, search memory, save a decision, and so on.
2. Five lifecycle hooks (.claude/settings.json). SessionStart injects a context pack as the session opens. UserPromptSubmit and PostToolUse quietly capture relevant context and verified commands as you work. Stop and PreCompact summarize the session back into memory before it's gone.
3. A CLAUDE.md instruction block + a Claude Code skill that teach Claude when to reach for those tools — pull context before non-trivial work, save the corrections and rules you hand it during work.

Features

• 🧠 Structured, typed memory — decisions, constraints, preferences, verified commands, task summaries, bug notes, open questions. Not one big blob; each kind is retrieved and ranked on its own terms.
• 🔍 Hybrid local-first search — Postgres full-text and pgvector semantic search, re-ranked in JS by recency, confidence, memory type, pinned status, and overlap with the files you mentioned. Embeddings run locally via Transformers.js (Xenova/all-MiniLM-L6-v2, 384-dim) — no API calls. With embeddings off or unavailable, it degrades cleanly to keyword-only.
• 🪝 Automatic capture via hooks — the good stuff gets saved without you remembering to ask, summarized by the Claude Agent SDK with a heuristic fallback when the SDK isn't reachable.
• 🛡️ Secret redaction — private keys, credentialed connection strings, and .env dumps are refused outright; JWTs, API keys, and bearer tokens are masked inline before anything touches the database. Full transcripts and raw terminal output are never stored.
• 📋 A local dashboard for reviewing, editing, pinning, and deleting what the AI captured — because auto-captured memory is never perfect, and a human should get the last word.
• 💻 Local-first, single-repo — each repository gets its own memory space, keyed to its path. Your data, your Postgres, offline-friendly.

Quick start

Prerequisites: Node >= 20 and Docker (or your own pgvector-enabled Postgres).

# 1. Install the CLI
npm i -g @notnessie/cli

# 2. Start NotNessie's database — ships its own Compose file, auto-picks a free port
notnessie pgup

# 3. Inside the repo you want Claude to remember:
notnessie init       # writes .mcp.json, the CLAUDE.md block, the skill, hooks, and config
notnessie status     # health check: database, schema, embeddings, Claude Code wiring

Then open Claude Code in the repo. The MCP tools load from .mcp.json, the hooks from .claude/settings.json, and Claude starts with a context pack injected at SessionStart. Before non-trivial work it pulls context; after, it saves what's worth keeping.

Already have a pgvector Postgres? Skip notnessie pgup and point NotNessie at it with DATABASE_URL:

export DATABASE_URL=postgres://user:pass@host:5432/dbname

Try it without Claude Code

NotNessie is fully usable from the terminal, which is the fastest way to get a feel for it:

notnessie seed                                          # load a coherent demo dataset (an auth module)
notnessie context "add refresh token rotation to auth"  # see the context pack Claude would receive
notnessie search "refresh token" --types decision,constraint
notnessie dev                                           # open the dashboard at http://localhost:4319

MCP tools

The MCP server exposes nine tools (stdio by default, with a Streamable HTTP transport on port 4320 for the curious):

Tool	Purpose
notnessie_get_project_context	Compact, task-aware context pack for the current repo
notnessie_search_memory	Hybrid keyword + semantic search across stored memory
notnessie_save_decision	Record an architectural or implementation decision
notnessie_save_preference	Record a coding preference
notnessie_save_constraint	Record a hard rule, with a severity
notnessie_save_verified_command	Record a command confirmed to work in this repo
notnessie_save_task_summary	Record a post-task summary (files changed, commands run, TODOs)
notnessie_get_open_questions	List unresolved questions worth surfacing
notnessie_get_verified_commands	List commands previously verified here

How memory flows

   SessionStart hook              during the session                Stop / PreCompact hooks
┌────────────────────┐       ┌────────────────────────┐       ┌──────────────────────────┐
│  context pack is   │  ──▶  │  Claude pulls context, │  ──▶  │  the session is          │
│  injected as the   │       │  you correct & decide, │       │  summarized back into    │
│  session opens     │       │  saves happen via MCP  │       │  memory before it's lost │
└────────────────────┘       └────────────────────────┘       └──────────────────────────┘
         ▲                                                                  │
         └──────────────────────────────────────────────────────────────────┘
                    next session starts warm, not cold

In short: context comes in at the start, useful facts are saved during the work (by Claude through the MCP tools, and by the hooks watching quietly), and a summary goes back out at the end. Each session leaves the repo a little smarter than it found it.

CLI

The notnessie bin covers the whole loop:

notnessie init [path]                 Scaffold Claude Code integration + config
notnessie status [path]               Health of database, schema, embeddings, wiring
notnessie pgup                        Start the bundled Postgres (auto-picks a free port)
notnessie pgdown [--volume]           Stop the database (--volume also deletes all memory)
notnessie mcp [--http] [-p <port>]    Start the MCP server (stdio default; HTTP on 4320)
notnessie dev [-p <port>]             Launch the dashboard (default port 4319)
notnessie search <query>              Search memory (--types, --limit, --json)
notnessie context [task]              Build a context pack (Markdown, or --json)
notnessie seed                        Load the demo memory dataset
notnessie memory list|show|delete|restore|pin|unpin
notnessie hook <event>               Run a lifecycle hook (Claude Code calls these, not you)

Configuration

NotNessie reads DATABASE_URL and embedding settings from your environment (and from a local .env, thanks to Node's built-in loader). The key variables:

Variable	Default	Purpose
DATABASE_URL	postgres://notnessie:notnessie@localhost:5432/notnessie	Postgres connection used by every package
NOTNESSIE_EMBEDDINGS	1	Set to 0 to disable local embeddings (keyword-only search)
NOTNESSIE_EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	The Transformers.js model used for semantic search
NOTNESSIE_DASHBOARD_PORT	4319	Port for notnessie dev

Per-repo behavior lives in .notnessie/config.json (written by init):

{
  "projectName": "my-project",
  "projectId": "proj_…",
  "memoryMode": "conservative",
  "autoSaveTaskSummaries": true,
  "autoSaveCommands": true,
  "autoSaveFileChanges": false,
  "redactSecrets": true
}

See .env.example for the full set, and the documentation site for the complete reference.

Under the hood

A pnpm + TypeScript monorepo (ESM, Node >= 20), built with tsup, tested with Vitest, linted with Biome:

• @notnessie/core — types, Postgres storage, redaction, embeddings, hybrid search, context packs, the summarizer.
• @notnessie/mcp — the MCP server and the nine tools, over stdio and Streamable HTTP.
• @notnessie/cli — the notnessie bin (this is the package you install).
• @notnessie/dashboard — the Next.js review UI, launched via notnessie dev.
• examples/demo-repo — a pre-wired backend used to show the flow end to end.

Storage is PostgreSQL + pgvector, provisioned by the included docker-compose.yml. Defaults: Postgres on localhost:5432, dashboard on 4319, MCP HTTP on 4320.

From source / contributing

Clone the repo, then:

pnpm install
pnpm build         # build @notnessie/core, @notnessie/mcp, @notnessie/cli
pnpm test          # unit tests (no database required)
node packages/cli/dist/index.js pgup      # start Postgres (pgvector) on a free port
node packages/cli/dist/index.js status

💡 Semantic search needs onnxruntime-node's native binary, whose install pnpm defers until you run pnpm approve-builds. Until then (or offline, or with NOTNESSIE_EMBEDDINGS=0), retrieval runs keyword-only — and turning the build on later activates semantic ranking with no code change.

Issues and PRs welcome at github.com/GreXLin85/notnessie.

A nod to Nessie

The name is an affectionate homage to Nessie (by Nessie Labs) — "Make your thinking legible to every AI you use." Nessie ingests and syncs your AI conversation history across ChatGPT, Claude, Gemini, Claude Code, Codex, and more, structures it into reusable context, and exposes it over an MCP server so your agents can query your history. It's cloud-synced, team-oriented, and permission-gated — a genuinely broader take on the idea.

NotNessie is a much narrower, local-first riff on that same north star: one project's memory, in your own local Postgres, scoped to a single repo. It's an independent, open-source experiment and is not affiliated with, endorsed by, or connected to Nessie or Nessie Labs in any way. The name is just a friendly tip of the hat. If you want the full, cross-tool, team-grade version of "make your context legible to AI," go look at the real thing. 🦕

Vibe-coded, human-reviewed

Honest disclosure: NotNessie was vibe-coded — built fast and largely with AI assistance (Claude Code itself, fittingly). It was then reviewed by a human for architecture, storage, security, privacy, and MCP behavior. AI wrote a lot of the lines; a person owns the scope, the security rules, and the decisions. That's rather the whole point of the project.

License

MIT — see LICENSE.