feat: add built-in per-repo memory tools #22

Merged
sam merged 2 commits from feat/memory-tools into main 2026-10-04 09:48:58 +00:00
Collaborator

Implements the ADK memory.Service over a per-repo SQLite store, so the native load_memory/preload_memory tools and four curation tools (create_memory, add_observations, delete_memory, read_graph) share one store, modeled after the reference MCP memory server (https://github.com/modelcontextprotocol/servers/tree/main/src/memory).

Design

  • ADK primitives, no custom abstractions: implements google.golang.org/adk/v2/memory.Service; the two read tools are ADK's native loadmemorytool/preloadmemorytool, wired through runner.Config.MemoryService.
  • Organised by repo: every operation is scoped to the git repo root found by walking up from the session working directory (same anchor as the file tools); directories outside any repo share a default memory. Entries from different repos never mix.
  • Row-level SQLite (memory.db under the state dir, WAL + _txlock=immediate): no whole-file rewrites, and two agents working the same repo serialize writes through SQLite's file locks. -ephemeral keeps the store in memory only.
  • GORM generics (gorm.G[T]) for reads; writes via plain chained calls (need RowsAffected for idempotency reporting).
  • Deterministic entry ids (entity:<name>, obs:<name>:<hash>, rel:<from>:<to>:<type>) make creates idempotent by primary key (OnConflict DoNothing), matching the MCP reference dedupe semantics.
  • Curated only: AddSessionToMemory refuses, so memory never ingests whole conversations — only the small facts the model writes with the curation tools.
  • 6 always-visible tools total: load_memory, preload_memory, create_memory(entities?, relations?), add_observations, delete_memory(entities?, observations?, relations?), read_graph(names?).

Files

  • internal/tools/memory.go — the memory.Service implementation (store + graph ops + search)
  • internal/tools/memory_tools.go — the four curation tools plus native tool registration
  • internal/tools/memory_test.go — 15 tests: roundtrip, idempotency, endpoint validation, cascade delete, repo isolation, search scoping, ephemeral mode, concurrent creates
  • internal/harness/harness.go — runner MemoryService, tool registration, always-visible set, tool-kind mappings
  • README + go.mod (gorm.io/gorm promoted to direct dependency)

Notes

  • from/to are SQLite reserved words and are backtick-quoted in raw WHERE clauses.
  • Observations are sorted in graph output because SQL row order is nondeterministic.
  • ADK's session/database owns session storage and uses the classic gorm API internally; that code is upstream and out of scope here.
Implements the ADK `memory.Service` over a per-repo SQLite store, so the native `load_memory`/`preload_memory` tools and four curation tools (`create_memory`, `add_observations`, `delete_memory`, `read_graph`) share one store, modeled after the reference MCP memory server (https://github.com/modelcontextprotocol/servers/tree/main/src/memory). ## Design - **ADK primitives, no custom abstractions**: implements `google.golang.org/adk/v2/memory.Service`; the two read tools are ADK's native `loadmemorytool`/`preloadmemorytool`, wired through `runner.Config.MemoryService`. - **Organised by repo**: every operation is scoped to the git repo root found by walking up from the session working directory (same anchor as the file tools); directories outside any repo share a `default` memory. Entries from different repos never mix. - **Row-level SQLite** (`memory.db` under the state dir, WAL + `_txlock=immediate`): no whole-file rewrites, and two agents working the same repo serialize writes through SQLite's file locks. `-ephemeral` keeps the store in memory only. - **GORM generics** (`gorm.G[T]`) for reads; writes via plain chained calls (need RowsAffected for idempotency reporting). - **Deterministic entry ids** (`entity:<name>`, `obs:<name>:<hash>`, `rel:<from>:<to>:<type>`) make creates idempotent by primary key (`OnConflict DoNothing`), matching the MCP reference dedupe semantics. - **Curated only**: `AddSessionToMemory` refuses, so memory never ingests whole conversations — only the small facts the model writes with the curation tools. - **6 always-visible tools** total: `load_memory`, `preload_memory`, `create_memory(entities?, relations?)`, `add_observations`, `delete_memory(entities?, observations?, relations?)`, `read_graph(names?)`. ## Files - `internal/tools/memory.go` — the `memory.Service` implementation (store + graph ops + search) - `internal/tools/memory_tools.go` — the four curation tools plus native tool registration - `internal/tools/memory_test.go` — 15 tests: roundtrip, idempotency, endpoint validation, cascade delete, repo isolation, search scoping, ephemeral mode, concurrent creates - `internal/harness/harness.go` — runner `MemoryService`, tool registration, always-visible set, tool-kind mappings - README + go.mod (gorm.io/gorm promoted to direct dependency) ## Notes - `from`/`to` are SQLite reserved words and are backtick-quoted in raw WHERE clauses. - Observations are sorted in graph output because SQL row order is nondeterministic. - ADK's `session/database` owns session storage and uses the classic gorm API internally; that code is upstream and out of scope here.
feat: add built-in per-repo memory tools
All checks were successful
code-review / Agent review (pull_request) Successful in 8s
315bca9961
Implement the ADK memory.Service over a per-repo SQLite store so the native
load_memory/preload_memory tools and four curation tools (create_memory,
add_observations, delete_memory, read_graph) share one store, modeled after
the reference MCP memory server.

- Entries stored as ADK memory.Entry rows keyed per repo root of the session
  cwd; deterministic ids make creates idempotent by primary key
- WAL + _txlock=immediate serializes two agents in one repo; :memory: in
  -ephemeral mode; gorm generics (gorm.G[T]) for reads
- AddSessionToMemory refuses: memory holds only curated facts, never whole
  conversations
- Harness wires MemoryService into the runner and registers all six tools as
  always-visible
pi-reviewer left a comment

AI-driven review: feat: add built-in per-repo memory tools

Reviewed against the samber/cc-skills-golang skill set (code-style/naming/docs, error-handling/safety/concurrency, security/dependencies, testing/perf/observability/modernize). One 🔴 blocking correctness bug, three suggestions — inline comments below.

Verification performed in this session on a fresh clone of the PR head 315bca9 (all API/dependency claims proven, not recalled):

  • go build ./... — clean; go vet ./internal/tools/ ./internal/harness/ — clean
  • go test ./... — all PR tests pass; racedetector test ./internal/tools/ — no data races; golangci-lint run ./internal/tools/ ./internal/harness/ — 0 issues on PR code
  • go doc google.golang.org/adk/v2/memory.Service — interface is exactly {AddSessionToMemory, SearchMemory}; runner.Config.MemoryService exists and is wired into the invocation context (adk runner.go:677-679); loadmemorytool/preloadmemorytool call ctx.SearchMemory — the harness wiring is correct
  • glebarez/go-sqlite driver source: sets pragma BUSY_TIMEOUT(5000) per connection and validates _txlock=immediate + _pragma=journal_mode(WAL) — the cross-process write-serialization claim holds
  • go list -m -versions gorm.io/gorm — v1.31.2 is the latest release; the indirect→direct promotion is correct (gorm.G, gorm.DB, clause used directly); ADK in-memory search scoring (memory/inmemory.go) matches the mirroring claim
  • govulncheck ./internal/tools/ — 0 reachable vulnerabilities; the 2 module-level findings (grpc GO-2026-6443, x/crypto openpgp GO-2026-5932) are pre-existing indirect deps untouched by this PR

Strengths (not re-commented inline): consistently wrapped %w errors; all SQL parameterized (no injection surface); deterministic IDs + OnConflict DoNothing idempotency is sound; WAL + _txlock=immediate + driver busy-timeout make the two-agent claim real; 15 parallel tests pass under the race detector; README is thorough and accurate except the one observation claim flagged inline.

## AI-driven review: feat: add built-in per-repo memory tools Reviewed against the samber/cc-skills-golang skill set (code-style/naming/docs, error-handling/safety/concurrency, security/dependencies, testing/perf/observability/modernize). One 🔴 blocking correctness bug, three suggestions — inline comments below. **Verification performed in this session** on a fresh clone of the PR head `315bca9` (all API/dependency claims proven, not recalled): - `go build ./...` — clean; `go vet ./internal/tools/ ./internal/harness/` — clean - `go test ./...` — all PR tests pass; `racedetector test ./internal/tools/` — no data races; `golangci-lint run ./internal/tools/ ./internal/harness/` — 0 issues on PR code - `go doc google.golang.org/adk/v2/memory.Service` — interface is exactly {AddSessionToMemory, SearchMemory}; `runner.Config.MemoryService` exists and is wired into the invocation context (adk runner.go:677-679); `loadmemorytool`/`preloadmemorytool` call `ctx.SearchMemory` — the harness wiring is correct - glebarez/go-sqlite driver source: sets `pragma BUSY_TIMEOUT(5000)` per connection and validates `_txlock=immediate` + `_pragma=journal_mode(WAL)` — the cross-process write-serialization claim holds - `go list -m -versions gorm.io/gorm` — v1.31.2 is the latest release; the indirect→direct promotion is correct (gorm.G, gorm.DB, clause used directly); ADK in-memory search scoring (memory/inmemory.go) matches the mirroring claim - `govulncheck ./internal/tools/` — 0 reachable vulnerabilities; the 2 module-level findings (grpc GO-2026-6443, x/crypto openpgp GO-2026-5932) are pre-existing indirect deps untouched by this PR **Strengths (not re-commented inline):** consistently wrapped `%w` errors; all SQL parameterized (no injection surface); deterministic IDs + `OnConflict DoNothing` idempotency is sound; WAL + `_txlock=immediate` + driver busy-timeout make the two-agent claim real; 15 parallel tests pass under the race detector; README is thorough and accurate except the one observation claim flagged inline.
@ -729,3 +751,3 @@
return acp.ToolKindFetch
case strings.Contains(lower, "read"), strings.Contains(lower, "get"), strings.Contains(lower, "list"),
strings.Contains(lower, "inspect"), strings.Contains(lower, "capture"):
strings.Contains(lower, "inspect"), strings.Contains(lower, "capture"), strings.Contains(lower, "load"):
Collaborator

🟡 SUGGESTION — substring matching on "load" and "add" misclassifies unrelated MCP tools. Every connected tool whose name contains "load" (e.g. upload_file, download_file, reload_config, payload_*) is now classified ToolKindRead, and any containing "add" (e.g. address_lookup, addon_*) becomes ToolKindEdit; before this PR those names fell through to the default "". The memory feature only needs two names. Fix: match the memory tools exactly (name == "load_memory" || name == "preload_memory", and name == "add_observations") before the substring cases, or use word-boundary matching.

🟡 **SUGGESTION — substring matching on "load" and "add" misclassifies unrelated MCP tools.** Every connected tool whose name contains "load" (e.g. `upload_file`, `download_file`, `reload_config`, `payload_*`) is now classified `ToolKindRead`, and any containing "add" (e.g. `address_lookup`, `addon_*`) becomes `ToolKindEdit`; before this PR those names fell through to the default `""`. The memory feature only needs two names. Fix: match the memory tools exactly (`name == "load_memory" || name == "preload_memory"`, and `name == "add_observations"`) before the substring cases, or use word-boundary matching.
@ -0,0 +606,4 @@
// the requested set stay discoverable.
func (m *Memory) openNodes(ctx context.Context, repo string, names []string) (graphResult, error) {
entries, err := gorm.G[memoryEntry](m.db).
Where("repo = ? AND (kind = ? AND entity_name IN ? OR kind = ? AND (`from` IN ? OR `to` IN ?))",
Collaborator

🔴 BLOCKING — read_graph(names) silently drops every observation. The WHERE clause selects only entity rows (kind = 'entity') and relation rows (kind = 'relation'); observation rows (kind = 'observation') are never fetched, so groupGraph returns the named entities with empty observations. Reproduced with a scratch test in this session: go test ./internal/tools/ -run TestReviewOpenNodesObservations fails with openNodes observations for alice: [] (len=0) while alice has 2 stored observations. This contradicts the README and the tool description ("with names, those entities with their observations plus every relation touching either of them"). TestMemoryOpenNodes passes only because it never asserts observations. Fix: add the observation rows to the predicate, e.g. Where("repo = ? AND ((kind = ? AND entity_name IN ?) OR (kind = ? AND entity_name IN ?) OR (kind = ? AND (fromIN ? ORto IN ?)))", repo, kindEntity, names, kindObservation, names, kindRelation, names, names).

🔴 **BLOCKING — `read_graph(names)` silently drops every observation.** The WHERE clause selects only entity rows (`kind = 'entity'`) and relation rows (`kind = 'relation'`); observation rows (`kind = 'observation'`) are never fetched, so `groupGraph` returns the named entities with empty `observations`. Reproduced with a scratch test in this session: `go test ./internal/tools/ -run TestReviewOpenNodesObservations` fails with `openNodes observations for alice: [] (len=0)` while alice has 2 stored observations. This contradicts the README and the tool description ("with names, those entities with their observations plus every relation touching either of them"). `TestMemoryOpenNodes` passes only because it never asserts observations. Fix: add the observation rows to the predicate, e.g. `Where("repo = ? AND ((kind = ? AND entity_name IN ?) OR (kind = ? AND entity_name IN ?) OR (kind = ? AND (`from` IN ? OR `to` IN ?)))", repo, kindEntity, names, kindObservation, names, kindRelation, names, names)`.
@ -0,0 +704,4 @@
// observationContent is the display text of one observation: the owning
// entity's name followed by the observation, so load_memory results show which
// entity each fact belongs to.
func observationContent(entityName, observation string) string {
Collaborator

🟡 SUGGESTION — searching an entity name never surfaces its observations. observationContent stores "alice: likes coffee", so tokenizing (entryMatches) yields alice: (with colon) and the whole-token ASCII match alice: != alice never hits. Reproduced: go test ./internal/tools/ -run TestReviewSearchFindsObservations — hits for query "alice" are only ["Entity alice (type person)"]; the observation rows never match, so load_memory/preload_memory under-recall exactly the curated facts this feature exists to surface. Note TestMemorySearch's "want 2" assertion codifies the gap (entity + relation match, observation skipped). Fix options: store observation content without the "<name>: " prefix (the owning entity is already in the entity_name column and metadata), or strip the prefix before tokenizing, or treat the first token "<name>": as the name.

🟡 **SUGGESTION — searching an entity name never surfaces its observations.** `observationContent` stores `"alice: likes coffee"`, so tokenizing (entryMatches) yields `alice:` (with colon) and the whole-token ASCII match `alice:` != `alice` never hits. Reproduced: `go test ./internal/tools/ -run TestReviewSearchFindsObservations` — hits for query "alice" are only `["Entity alice (type person)"]`; the observation rows never match, so `load_memory`/`preload_memory` under-recall exactly the curated facts this feature exists to surface. Note `TestMemorySearch`'s "want 2" assertion codifies the gap (entity + relation match, observation skipped). Fix options: store observation content without the `"<name>: "` prefix (the owning entity is already in the `entity_name` column and metadata), or strip the prefix before tokenizing, or treat the first token `"<name>":` as the name.
@ -0,0 +309,4 @@
return toolResult{Output: "Nothing deleted: nothing matched."}, nil
}
out := "Deleted " + strings.Join(parts, ", ") + "."
Collaborator

🟡 SUGGESTION — malformed output when nothing is deleted. When every requested entity is missing, parts is empty and strings.Join(parts, ", ") yields "", so the tool answers Deleted . (entities not found: ghost) (space-dot). Reproduced: go test ./internal/tools/ -run TestReviewDeleteNothingOutput → output: "Deleted . (entities not found: ghost)". Fix: only emit the "Deleted ..." sentence when len(parts) > 0; otherwise return the notes alone.

🟡 **SUGGESTION — malformed output when nothing is deleted.** When every requested entity is missing, `parts` is empty and `strings.Join(parts, ", ")` yields "", so the tool answers `Deleted . (entities not found: ghost)` (space-dot). Reproduced: `go test ./internal/tools/ -run TestReviewDeleteNothingOutput` → `output: "Deleted . (entities not found: ghost)"`. Fix: only emit the `"Deleted ..."` sentence when `len(parts) > 0`; otherwise return the notes alone.
- open_nodes now fetches observation rows too, so read_graph(names) returns
  the named entities with their observations instead of silently dropping them
- search matches an observation when the query word is the owning entity's
  name, so load_memory/preload_memory surface curated facts by entity
- delete_memory no longer emits a dangling "Deleted ." sentence when
  everything requested is missing
- toolKind maps load_memory/preload_memory/add_observations exactly instead of
  substring-matching "load"/"add", which misclassified unrelated MCP tools
Author
Collaborator

All four review findings resolved in dc2ab6a. Verification: full suite + golangci-lint 0 issues; the fixes are covered by updated/extended tests.

  1. 🔴 open_nodes drops observations (comment 812) — fixed. openNodes now includes observation rows (kind = 'observation' AND entity_name IN ?) in the WHERE predicate, so read_graph(names) returns the named entities with their observations. TestMemoryOpenNodes now asserts alice's observations come through.
  2. 🟡 search never surfaces observations (comment 813) — fixed. entryMatches now matches an observation row when the query word equals the owning entity's name, so load_memory/preload_memory find the curated facts by entity despite the <name>: display prefix. TestMemorySearch now expects all 3 alice entries (entity, observation, relation).
  3. 🟡 "Deleted ." on all-missing deletes (comment 814) — fixed. The notes-only path no longer emits the empty sentence; TestMemoryDeleteNothingOutput asserts (entities not found: ghost).
  4. 🟡 "load"/"add" substring misclassification (comment 815) — fixed. toolKind matches load_memory/preload_memory/add_observations exactly in the built-in switch; the "load"/"add" substrings were removed. TestToolKind now pins upload_file, download_file, reload_config, payload_status, address_lookup, addon_install to "".
All four review findings resolved in dc2ab6a. Verification: full suite + golangci-lint 0 issues; the fixes are covered by updated/extended tests. 1. **🔴 open_nodes drops observations (comment 812)** — fixed. `openNodes` now includes observation rows (`kind = 'observation' AND entity_name IN ?`) in the WHERE predicate, so `read_graph(names)` returns the named entities with their observations. `TestMemoryOpenNodes` now asserts alice's observations come through. 2. **🟡 search never surfaces observations (comment 813)** — fixed. `entryMatches` now matches an observation row when the query word equals the owning entity's name, so `load_memory`/`preload_memory` find the curated facts by entity despite the `<name>: ` display prefix. `TestMemorySearch` now expects all 3 alice entries (entity, observation, relation). 3. **🟡 "Deleted ." on all-missing deletes (comment 814)** — fixed. The notes-only path no longer emits the empty sentence; `TestMemoryDeleteNothingOutput` asserts `(entities not found: ghost)`. 4. **🟡 "load"/"add" substring misclassification (comment 815)** — fixed. `toolKind` matches `load_memory`/`preload_memory`/`add_observations` exactly in the built-in switch; the `"load"`/`"add"` substrings were removed. `TestToolKind` now pins `upload_file`, `download_file`, `reload_config`, `payload_status`, `address_lookup`, `addon_install` to `""`.
sam merged commit 4c22d178eb into main 2026-10-04 09:48:58 +00:00
sam deleted branch feat/memory-tools 2026-10-04 09:48:58 +00:00
Sign in to join this conversation.
No reviewers
No labels
code-review
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
sam/brainless!22
No description provided.