notnessie

Quick start

This page shows the two ways to use NotNessie: with Claude Code (the intended flow), and standalone from the CLI for trying it out or scripting.

If you have not installed NotNessie yet, start with Installation.

With Claude Code

Once you have run notnessie pgup and notnessie init, the integration is automatic. Open Claude Code in the repository and just work — there is no extra command to remember.

What happens behind the scenes:

  1. On session start, the SessionStart hook injects a context pack so Claude begins with the repo’s relevant decisions, constraints, verified commands, and open questions.
  2. Before non-trivial work, Claude calls notnessie_get_project_context (and notnessie_search_memory for a specific module, bug, or API), guided by the skill and the CLAUDE.md block.
  3. As you work, Claude saves durable facts — a decision (“we decided to use Redis”), a constraint (“never edit generated files”), a preference, or a verified command. The PostToolUse hook also records build/test commands it sees succeed.
  4. When the session ends or is compacted, the Stop / PreCompact hooks summarize it into memory.

You can nudge it explicitly in chat, for example:

Remember that we use PostgreSQL, not MySQL, for this project.
Save a verified command: pnpm test runs the unit suite.
What did we decide about refresh tokens? Check project memory.

Claude maps these to the matching MCP tools.

!!! tip “Curate as you go” Automatically captured memory is not perfect. Open the dashboard periodically to fix, pin, or delete memories. Pinned memories rank first in every context pack.

Standalone (without Claude Code)

The same memory is reachable directly from the CLI. This is the fastest way to see what NotNessie does.

Load the demo dataset

seed populates the current project with a coherent demo dataset (an auth-module example) so you have something to explore:

notnessie seed

Build a context pack

context generates the same compact, task-aware pack the assistant receives. Markdown by default; add --json for the structured form:

notnessie context "add refresh token rotation to auth"
notnessie context "add refresh token rotation to auth" --json

With no task, you get a general project pack:

notnessie context

Search memory

search runs the hybrid keyword + semantic ranking and prints ranked matches. Filter by type and limit the count:

notnessie search "refresh token"
notnessie search "refresh token" --types decision,constraint
notnessie search "refresh token" --limit 5 --json

Review and curate (the dashboard)

dev runs the local daemon and the Next.js dashboard, where you scan memory by type, open a memory to verify or edit it, delete noise, restore mistakes, and pin what matters:

notnessie dev

The dashboard runs on http://localhost:4319 by default (override with -p or NOTNESSIE_DASHBOARD_PORT).

Manage individual memories

The memory subcommands operate on single memories by id (get ids from notnessie memory list):

notnessie memory list                       # newest first
notnessie memory list --types decision      # filter by type
notnessie memory show <id>                  # full memory + its source
notnessie memory pin <id>                   # rank it first
notnessie memory delete <id>                # soft delete (restorable)
notnessie memory restore <id>               # undo a soft delete
notnessie memory delete <id> --hard         # permanent

See the full CLI reference for every command and option.

A note on embeddings

Semantic search uses a local Transformers.js model that downloads on first use. Until it is available — offline, or with NOTNESSIE_EMBEDDINGS=0 — retrieval runs keyword-only and nothing breaks. Enabling embeddings later activates semantic ranking with no code change. See Configuration and Architecture.

This site is open source. Improve this page.