NotNessie is local-first: it runs entirely on your machine and stores memory in your own Postgres. This page covers prerequisites, installing the CLI, starting the database, and wiring NotNessie into a repository.
.env loading.)pgvector extension. If you already run a pgvector-enabled Postgres, you can
point NotNessie at it instead via DATABASE_URL (see
Bring your own Postgres).!!! tip “Claude Code” NotNessie is built for Claude Code. You can use the CLI standalone (see the Quick start), but the integration shines when Claude Code is driving it through the MCP server and hooks.
Install the notnessie command globally:
npm i -g @notnessie/cli
This puts the notnessie binary on your PATH. Verify it:
notnessie --version
!!! note “Running from a clone instead”
If you are working from a checkout of the repository rather than the
published package, see Contributing for the
pnpm install / pnpm build workflow. The same commands apply afterward.
The easiest way is to let NotNessie manage Postgres for you. From any directory, run:
notnessie pgup
This ships its own Compose file (no repo checkout needed), starts a
pgvector/pgvector:pg16 container named notnessie-postgres, and
automatically picks a free host port if the default 5432 is already taken —
so it never collides with another Postgres you happen to be running. It then
records the connection in a user-level config file (~/.notnessie/db.json) that
every repository picks up automatically — you do not need to set
DATABASE_URL or keep a .env. A named volume keeps your memory across restarts.
Stop it any time:
notnessie pgdown # stop the container (data is preserved)
notnessie pgdown --volume # also delete the data volume (removes all memory)
See notnessie pgup for details.
!!! note “Prefer to run Compose yourself?”
The repository also ships a docker-compose.yml. From a clone you can run
docker compose up -d directly and override credentials/port with
NOTNESSIE_DB_USER, NOTNESSIE_DB_PASSWORD, NOTNESSIE_DB_NAME, and
NOTNESSIE_DB_PORT. See Configuration.
If you would rather use an existing PostgreSQL instance, you need the
pgvector extension available. Point NotNessie at it by setting DATABASE_URL
(in your shell, or a repo .env):
DATABASE_URL=postgres://user:password@host:5432/dbname
NotNessie resolves the connection in this order: the DATABASE_URL environment
variable (including a repo .env), then the user-level config written by
notnessie pgup (~/.notnessie/db.json), then the built-in default:
postgres://notnessie:notnessie@localhost:5432/notnessie
Either way, NotNessie creates and migrates its own schema (tables, the tsvector
index, and the pgvector HNSW index) idempotently — you do not run migrations by
hand.
Change into the repository you want NotNessie to remember, and run:
cd path/to/your/repo
notnessie init
notnessie init scaffolds the Claude Code integration and project config. It
writes (without clobbering existing files unless you pass --force):
.mcp.json — registers the NotNessie MCP server..claude/settings.json — registers the five lifecycle hooks..claude/skills/notnessie/SKILL.md — the skill that tells Claude when to use
the tools..notnessie/config.json — per-project memory settings.CLAUDE.md — a NotNessie instruction block is merged in idempotently
(existing content is preserved).It then connects to the database and creates the project’s row and schema. If the
database is not reachable yet, init tells you how to start it and continue.
See notnessie init for the full option list.
Run the health check:
notnessie status
status reports the database connection, that the pgvector extension is present,
the schema state, whether embeddings are active, and the Claude Code wiring, plus
per-type memory counts. If everything is green, you are ready to
get started.