botnote

botnote

Notion for bots. A single binary that stores projects, tasks, notes, and agent memory — and exposes them to AI agents via MCP and REST.

Why

Agents work best with one stable, queryable, write-friendly source of truth — not a stack of Notion + Jira + Slack + scratch files. botnote is that source of truth, scoped to one user, deployable in 60 seconds.

Three things only:

1. Project management — projects and tasks with status, priority, due dates, and stable identifiers.
2. Note-taking — free-form Markdown notes, tagged, searchable, and optionally pinned.
3. Memory for agents — hybrid retrieval (BM25 + vector + time decay), opening brief auto-bundles AGENTS.md + recent context.

Design

• Storage: Postgres + pgvector + tsvector. Single dedicated docker container.
• Single multi-kind entity table — task / note discriminated by kind column.
• Search: hybrid retrieval — tsvector BM25 + pgvector cosine + time decay, merged via Reciprocal Rank Fusion (k=60).
• Embeddings: OpenAI text-embedding-3-small at 384 dimensions, written asynchronously. Falls back to BM25-only if no API key.
• API: MCP server (stdio) + REST API (Fastify on :4280) over a shared service layer.
• Every write records actorKind (human / agent / system); idempotencyKey is supported on writes.
• All MCP tools carry 2025-03-26 annotations: readOnlyHint, idempotentHint, destructiveHint, openWorldHint.

Quick start

Requires: Node 20+, pnpm, Docker.

CLI install

On client machines, install the portable CLI from npm:

npm i -g botnote
botnote login

botnote login stores the daemon URL and bearer token in ~/.config/botnote/config.json. Use https://botnote.net plus a token from Settings -> API tokens on remote machines; use http://127.0.0.1:4280 without a token on the daemon host. New API tokens remain copyable from Settings; tokens created before recoverable storage was added only show their prefix and should be regenerated if the full value was lost.

Security note: newly-created API tokens are stored recoverably in the database so Settings can copy them later. Treat the database and backups as secret-bearing material, and revoke tokens if either is exposed.

The Claude Code, Codex, and Cursor plugins call botnote mcp, so installing the npm package is enough for plugin runtime on machines that do not have a botnote source checkout.

Local daemon development

# 1. Spin up postgres (port 55434, pgvector extension)
docker compose up -d

# 2. Install deps
pnpm install

# 3. Apply schema
DATABASE_URL=[REDACTED:DB Connection String] pnpm db:migrate

# 4. Boot REST + Swagger UI
DATABASE_URL=[REDACTED:DB Connection String] pnpm dev

Then:

• REST API: http://localhost:4280
• Swagger UI: http://localhost:4280/docs
• OpenAPI JSON: http://localhost:4280/docs/json

Embeddings are optional. Set OPENAI_API_KEY to enable hybrid (BM25 + cosine) search; without it, search is BM25-only.

Tests

Tests must run against a disposable database whose name contains test. The helper refuses any other database name so local test runs do not touch a live botnote instance.

docker compose up -d
docker exec botnote-postgres createdb -U botnote botnote_test || true

DATABASE_URL=[REDACTED:DB Connection String] pnpm db:migrate
BOTNOTE_TEST_DATABASE_URL=[REDACTED:DB Connection String] pnpm test

REST endpoints

method	path	summary
POST	/v1/projects	Create project
GET	/v1/projects	List projects
GET	/v1/projects/:id	Fetch project
PATCH	/v1/projects/:id	Update project
GET	/v1/projects/by-key/:key	Fetch by key
POST	/v1/projects/:id/opening-brief	Opening brief
POST	/v1/opening-brief	Workspace or project opening brief
POST	/v1/tasks	Create task
POST	/v1/notes	Create note
GET	/v1/entities/:id	Fetch entity
PATCH	/v1/entities/:id	Update entity
DELETE	/v1/entities/:id	Delete entity
GET	/v1/entities/:id/related	List related entities
POST	/v1/entities/:id/links	Link entity to another
POST	/v1/recent	Recent activity
POST	/v1/search	Hybrid search
POST	/v1/tasks/range	Scheduled, overdue, and backlog tasks
GET	/v1/tokens	List API tokens
POST	/v1/tokens	Create API token
DELETE	/v1/tokens/:id	Revoke API token
GET	/health	Health check

Schemas: see /docs (Swagger UI) or /docs/json (OpenAPI 3).

Example: create a project + write a task + search

A=http://localhost:4280

PID=$(curl -s -X POST $A/v1/projects \
  -H 'content-type: application/json' \
  -d '{"key":"DEMO","name":"Demo","agentsMd":"ALWAYS run tests"}' \
  | jq -r .id)