memoryweb: Instructions file for Claude Code

@AGENTS.md

CLAUDE.md — coding agent instructions for memoryweb

Read this before touching any file in this repo.

---

What this repo is

memoryweb is a MCP (Model Context Protocol) server written in Go. It stores knowledge as a graph of nodes (concepts/decisions) connected by typed, narrative edges. It communicates over stdin/stdout using JSON-RPC 2.0.

The binary is long-lived: one process per MCP session. All state lives in a single SQLite file (WAL mode). There is no HTTP server, no daemon — just a loop reading lines from stdin and writing responses to stdout.

---

Package layout

db/ and tools/ are split by concern, one file per area — not one monolithic file per package. When adding a new Store method or tool handler, put it in the file for its concern; create a new file only for a genuinely new concern.

main.go               JSON-RPC 2.0 wire loop (stdin → dispatch → stdout)

db/store.go           Store type, New/Close (checkpoints WAL on close), Backup (VACUUM INTO snapshot), schema/version/stats queries, init()
db/migrations.go      migration type, the migrations slice, migrate() — append-only, see below
db/embeddings.go      Ollama embedding client, storeEmbedding, BackfillEmbeddings
db/nodes.go           Node struct, AddNode/GetNode/UpdateNode/ArchiveNode/RestoreNode/ListArchived, batch variants
db/edges.go           Edge struct, AddEdge/AddEdgesBatch/DeleteEdge, collectEdges
db/search.go          SearchNodes/SearchNodesExact, LIKE + semantic search paths
db/graph.go           FindPath/FindConnections/GetNodeNeighbourhood/GetDomainGraph, SuggestEdges
db/timeline.go        RecentChanges(Scoped), Timeline, GetHistoryForMemoryID
db/significance.go    GetSignificance and its memory_id/tags variants
db/audit.go           FindDrift/CountStaleDrift/FindDisconnected
db/domains.go         Alias CRUD, RenameDomain, MergeDomains, ListDomains
db/purge.go           Purge — the one hard-delete path; CLI-only, never an MCP tool, kept visually separate
db/util.go            slug(), shortID(), tagFilter, scanNodeRow(s), and the generic helpers below

tools/tools.go        Handler type, CallTool dispatch switch, Instructions const, shared small helpers
tools/definitions.go  ListTools() — the full MCP tool schema
tools/lean.go         Shared lean-entry helpers (leanEntry, toLeanEntry, truncateWhy, ...)
tools/remember.go     remember tool (addNode + batch)
tools/revise.go       revise tool (updateNode + batch)
tools/connect.go      connect/disconnect/suggest_connections
tools/search.go       search tool
tools/recent.go       recentChanges handler (history order=modified path; no MCP tool)
tools/history.go      history tool
tools/significance.go significance tool
tools/orient.go       orient tool (cross-domain snapshot, topic mode, full domain summary)
tools/domains.go      domains tool
tools/archive.go      forget/forget_all, audit tool, drift
tools/graph.go        why_connected, visualise

cmd/                  CLI-only subcommands (not MCP tools)
stats/                WKD session scoring and stats logging