Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (79 loc) · 9.21 KB

CLAUDE.md

File metadata and controls

113 lines (79 loc) · 9.21 KB
Raw

CLAUDE.md

Routing map for Claude. Points at the rule, skill, agent, or file that owns the answer — does not restate them.

Project at a glance

remindb — token-efficient agentic memory database. Single SQLite file, MCP server on top. Go 1.26+. Pre-1.0 beta, solo dev, no compatibility shims. dev is the integration trunk; main is a release-marker branch — one squash commit per published release, signed by GitHub's web-flow key via PR from dev. Topic branches (feat/, fix/, chore/, docs/) off dev, rc tags on dev, stable cuts tag dev then squash-PR dev → main; lazy release/vX.Y branches handle patches to non-current minors; subject-only signed commits everywhere (release squash on main carries the release notes as its body) — see .claude/rules/git-versioning.md.

Pipeline: parser → transformer → emitter → store. Read side: query → mcp/tools. Background: temperature ticker decays/notifies.

Code map

  • pkg/parser/ — file formats → AST nodes
  • pkg/transformer/ — AST → ContextNode tree
  • pkg/emitter/ — node tree → store snapshot
  • pkg/store/ — SQLite layer; queries.go holds SQL constants, methods live in node.go / snapshot.go / search.go / temperature.go
  • pkg/diff/ — snapshot diffing
  • pkg/query/ — search/fetch engine + result formatters (Format, FormatCompact)
  • pkg/compiler/ — full-workspace compile pipeline
  • pkg/mcp/ — MCP server; tools in pkg/mcp/tools/ (one file per tool)
  • pkg/temperature/ — decay/boost/cold-set + cold-node notifier
  • cmd/remindb/ — CLI: serve, compile, inspect, bench, doctor, update
  • migrations/ — 0001_init.sql, 0002_*.sql, applied via embed.FS in migrations.go
  • internal/ — bench, contentid, fileext, ignore, mcptest, tempfile, testutil, tokens
  • skills/{remember,remind,memorize,remindb-setup}/ — public skills shipped to MCP clients (distinct from .claude/skills/): remember is the broad-trigger router, remind the read path + mental model, memorize the write path + Markdown-shape rules, remindb-setup the /remindb-setup [automode] setup wizard. remind, memorize, and remindb-setup push depth into their references/ subdirs (progressive disclosure); SKILL.md stays a compact router/spine. Structural gate: scripts/check-skills.sh (make check-skills)
  • docs/ — public end-user manual: architecture.md / cli.md / configuration.md (reference) plus one deep-dive per feature; editable diagram sources in assets/excalidraw/, exported assets/*.svg
  • plugins/ — per-agent plugin folders (claude-code, gemini-cli, codex, opencode, openclaw)
  • Top-level: integration_test.go, mcp_integration_test.go, bench_test.go

Where to read first — don't grep, don't ls

Question Source
End-to-end product story, benchmarks, feature pitch README.md
Architecture, CLI, .remindb/ config (reference) docs/architecture.md · docs/cli.md · docs/configuration.md
Feature deep-dive — node tree · temperature · versioning · search · TOON · MathML→LaTeX · knowledge graph · resources the matching docs/<topic>.md
How clients call the MCP read tools (the contract) skills/remind/SKILL.md + skills/remind/references/
How clients author content for MCP write tools (the contract) skills/memorize/SKILL.md + skills/memorize/references/
Plain-language memory front door · connecting/configuring remindb skills/remember/SKILL.md · skills/remindb-setup/SKILL.md
Go style, naming, error/log/concurrency idioms .claude/rules/go-concise.md
Commit, sign, branch, tag, push, release rules .claude/rules/git-versioning.md
MCP tool contract (signature, locking, returns) .claude/rules/mcp-tool-conventions.md
slog levels, fields, what never logs .claude/rules/logging-conventions.md
User & feedback memory across sessions .claude/projects/-home-radimsem-personal-projects-remindb/memory/MEMORY.md (auto-loaded)

Tread carefully — pause before implementing

These zones have either an external contract or a silent-drift hazard. Don't change them blind; the linked skill or rule encodes the discipline that prevents the foot-gun.

MCP tool surface (pkg/mcp/tools/, pkg/mcp/server.go)

The Memory* tool suite is a contract shipped to clients via two public skills: skills/remind/SKILL.md (read tools — MemoryTree, MemorySearch, MemoryFetch, MemoryFetchBatch, MemoryDelta, MemoryDiff, MemoryHistory, MemoryRelated, MemoryStats) and skills/memorize/SKILL.md (write tools — MemoryWrite, MemorySummarize, MemoryCompile, MemoryRelate, MemoryForget, MemoryRollback, MemoryPin, MemoryUnpin). Each SKILL.md is a compact router; per-tool depth lives in its references/ subdir — when a change touches resource envelopes, FTS5 syntax, snapshot/relations mechanics, or the parser/lifecycle/wiki-link details, update the matching references/*.md, not just SKILL.md. Renaming, removing, or changing semantics breaks every client and desyncs the relevant public skill. Use the add-mcp-tool skill for any new/modified tool, follow .claude/rules/mcp-tool-conventions.md, and dispatch the mcp-surface-reviewer agent before merge.

SQLite schema & migrations (migrations/, pkg/store/)

Migrations are forward-only, applied at startup, and FTS5 triggers must stay in sync with the nodes table. Schema mistakes ship as broken .db files in user repos. Use the add-store-query skill (covers both query-only and migration-bearing changes) and dispatch the migration-safety-reviewer agent before merge.

Temperature policy (pkg/temperature/Config)

DecayRate, AccessBoost, ColdThreshold, NotifyThreshold, TickInterval are documented numerically in skills/remind/SKILL.md (mental model) and the summarization workflow they trigger lives in skills/memorize/references/lifecycle.md. Changing any one shifts search ranking, the cold-set query, and the client notification stream — both public skills drift silently. Use the tune-temperature-policy skill.

Snapshot atomicity

Each MemoryWrite / MemorySummarize / MemoryCompile call must produce exactly one emitter.Emit (one snapshot row). Two snapshots per intent fragments the diff trail clients walk via MemoryDelta. MemoryRelate is the deliberate exception — relation mutations are a sideband and must not call emitter.Emit. Detail in .claude/rules/mcp-tool-conventions.md §7.

Read vs. write tool discipline

Read tools (Search, Fetch, Tree, Delta, History, Related) never take Store.OpMu and always call boostResultNodes (or its equivalent — MemoryRelated uses boostRelatedNodes). Write tools (Write, Summarize, Compile, Relate) always take Store.OpMu and never boost. Mixing breaks ranking or serializes reads. Detail in .claude/rules/mcp-tool-conventions.md §5–6.

Sync primitives

Store.OpMu sync.Mutex is exposed as a field. Call .Lock() / .Unlock() directly. Do not wrap in LockOp / UnlockOp helpers — explicit project preference (see auto-memory feedback_sync_primitives.md).

Pre-1.0 beta — no compatibility shims

Solo, linear dev, small surface area, no committed-to-stable-API yet. Don't add deprecation paths, version gates, or backwards-compat wrappers. Just change the code and update the rule/skill that documents it.

Workflow shortcuts — task → skill

Task Skill
Add a new file format to the parser add-parser
Add or change an MCP Memory* tool add-mcp-tool
Add a SQL query, column, index, or migration add-store-query
Add a Fuzz* target or extend a seed corpus add-fuzz-target
Add an end-to-end scenario (integration_test.go, mcp_integration_test.go) add-integration-test
Add a token-savings benchmark scenario add-bench-scenario
Tune decay / cold / notify thresholds tune-temperature-policy

Reviewer agents (.claude/agents/): go-style-reviewer, mcp-surface-reviewer, migration-safety-reviewer — dispatch on relevant changes before commit.

Build & test

make build          # go build ./...
make test           # go test ./...
make test-all       # scripts/test.sh — full suite incl. integration
make fuzz           # scripts/fuzz.sh — bounded fuzz pass
make fmt lint tidy  # gofmt / golangci-lint / go mod tidy

Inspect a compiled DB: go run ./cmd/remindb inspect --db <path>. Run the server: go run ./cmd/remindb serve (add --verbose for Debug logs).

Benchmarks: scripts/bench-agents.sh runs the cross-agent token-savings table referenced in the README.

What this file is NOT

  • Not a Go style guide → .claude/rules/go-concise.md owns that.
  • Not the MCP contract spec → .claude/rules/mcp-tool-conventions.md + skills/remind/SKILL.md (read) + skills/memorize/SKILL.md (write).
  • Not a how-to for adding parsers/tools/queries → the .claude/skills/ workflow each owns its own checklist.
  • Not a changelog or task tracker → use commits and the conversation, not this file.

If a section here grows beyond a routing pointer, move the detail into the appropriate rule or skill and shrink this back to a one-liner.