Skip to content

memory-management.md

Latest commit

 

History

History
237 lines (177 loc) · 7.9 KB

memory-management.md

File metadata and controls

237 lines (177 loc) · 7.9 KB

Memory Management Example

Goal

Propose, write, and maintain Serena memories that capture durable project facts — then periodically clean up memories that have become stale, incorrect, or misplaced.

Quick Reference

/memory-propose

Proposes new memories without writing anything. Outputs a structured proposal for review before committing.

Expected output sections:

  • Proposed memories — names and categories for each candidate
  • Draft content — what each memory will say
  • Rationale — why each fact is durable and session-agnostic

/memory-write

Writes one or more approved memories to the Serena memory store.

Expected output sections:

  • Written memories — path and one-line summary for each
  • Skipped — any proposals rejected and why
  • Verification — get_symbols_overview or find_symbol calls confirming the facts are still accurate at write time

/memory-cleanup

Audits existing memories for staleness, inaccuracy, and misplacement.

Expected output sections:

  • Valid memories — confirmed still accurate
  • Potentially stale — need a find_symbol / get_symbols_overview check
  • Definitely stale — contradicted by current codebase
  • Proposed actions — delete / update / rename for each flagged memory

Full Workflow: Build-and-Test Memory

Step 1 — Propose

/memory-propose document the Go build and test workflow for the task service

Example output:

## Proposed Memories

**1. build-and-test/go-workflow**
- Category: `build-and-test/`
- Draft content:

Go build and test — task service

Build: go build ./... Test: go test ./... Lint: golangci-lint run ./... Vet: go vet ./...

Integration tests require TEST_DB_URL env var (see .env.example). Run integration suite: go test ./integration/... -tags integration

CI uses Go 1.22 (go.mod). Local toolchain should match.

- Rationale: These commands are stable across sessions; every agent that
touches the codebase needs them. Not storing them wastes tokens re-discovering
the Makefile or go.mod on every session.

**2. repo-structure/task-service**
- Category: `repo-structure/`
- Draft content:

Task service — package layout

internal/tasks/ domain: Task struct, TaskService interface internal/tasks/handler/ HTTP handlers (Chi router) internal/tasks/store/ PostgreSQL repository (pgx/v5) internal/tasks/worker/ background queue consumer (Redis) cmd/server/ main entrypoint api/openapi.yaml OpenAPI 3.1 spec (source of truth for HTTP contracts)

- Rationale: Package boundaries change rarely; capturing them avoids repeated
`get_symbols_overview` calls at session start.

**3. recurring-pitfalls/priority-defaults**
- Category: `recurring-pitfalls/`
- Draft content:

Task priority field — nil-pointer pitfall

The Priority field on Task is a pointer (*Priority). Request normalisation in completion_handler.go must nil-guard it before use; omitting the guard causes a runtime panic (fixed in commit a3f9c12, PR #214).

Always use: if req.Priority == nil { req.Priority = &DefaultPriority } before any dereference of Priority in request-handling code.

- Rationale: This bug recurs when new handlers are added. Storing it prevents
the same nil-dereference from being introduced again.

Step 2 — Write

/memory-write write the three proposed build-and-test, repo-structure, and recurring-pitfalls memories

Example output:

## Written Memories

| Path | Summary |
|---|---|
| `build-and-test/go-workflow` | Go build, test, lint, and vet commands for the task service |
| `repo-structure/task-service` | Package layout: domain, handler, store, worker, cmd |
| `recurring-pitfalls/priority-defaults` | Priority nil-pointer pitfall and required guard pattern |

## Skipped

None — all three proposals approved.

## Verification

- `get_symbols_overview internal/tasks` confirmed the package layout in the
  proposal matches the current directory structure (3 sub-packages: handler,
  store, worker).
- `find_symbol DefaultPriority` confirmed the constant exists in
  `internal/tasks/task.go:14` as expected by the pitfall memory.
- `go.mod` confirmed Go 1.22 toolchain version referenced in the build memory.

Step 3 — Cleanup

After several weeks of development the memory store has grown. Run a cleanup:

/memory-cleanup audit all memories in the task service project for staleness

Example output:

## Memory Audit

Checked 11 memories using `find_symbol` and `get_symbols_overview` to verify
facts against the current codebase.

### Valid Memories

| Memory | Verdict |
|---|---|
| `build-and-test/go-workflow` | Accurate — commands and Go version match go.mod |
| `recurring-pitfalls/priority-defaults` | Accurate — nil-guard still required; pattern still present |
| `repo-structure/task-service` | Accurate — package layout unchanged |
| `build-and-test/integration-test-setup` | Accurate — TEST_DB_URL still required |

### Potentially Stale (require confirmation)

**`repo-structure/http-router`**
- Memory says: "Uses Gorilla Mux for HTTP routing."
- `find_symbol Router` returns `chi.NewRouter` in `cmd/server/main.go:31`.
- Gorilla Mux was replaced with Chi in PR #301 (2026-02-14).
- Action: **Update** — replace "Gorilla Mux" with "Chi v5" and note the
  middleware registration pattern changed.

**`build-and-test/docker-compose`**
- Memory says: "Run `docker-compose up -d` to start dependencies."
- `find_symbol docker` returns no Compose file; the project now uses `devenv.nix`.
- Action: **Update** — replace with `devenv up` and note the Nix flake
  requirement.

### Definitely Stale

**`repo-structure/legacy-monolith`**
- Memory says: "The tasks package lives in `pkg/tasks/` (legacy monolith layout)."
- `get_symbols_overview pkg/` returns no results — `pkg/` does not exist.
- The monolith was split in Q1 2026; this memory describes the pre-split
  structure.
- Action: **Delete** — the directory no longer exists; the memory is actively
  misleading.

**`recurring-pitfalls/redis-pool-size`**
- Memory says: "Redis pool size must be set to 10 in config; default of 5
  causes connection exhaustion under load."
- `find_symbol RedisPoolSize` returns `DefaultPoolSize = 25` in
  `internal/worker/redis.go:8`.
- The default was raised in PR #389 (2026-03-29); the pitfall no longer applies.
- Action: **Delete** — the issue is resolved and the memory contradicts current
  defaults.

**`repo-structure/openapi-location`**
- Memory says: "OpenAPI spec is at `docs/openapi.yaml`."
- File does not exist at that path; `get_symbols_overview api/` returns
  `api/openapi.yaml`.
- Action: **Rename/Update** — correct path to `api/openapi.yaml`.

## Proposed Actions

| Memory | Action | Reason |
|---|---|---|
| `repo-structure/http-router` | Update | Gorilla Mux replaced by Chi v5 |
| `build-and-test/docker-compose` | Update | docker-compose replaced by devenv/Nix |
| `repo-structure/legacy-monolith` | Delete | Directory does not exist |
| `recurring-pitfalls/redis-pool-size` | Delete | Issue resolved; memory contradicts codebase |
| `repo-structure/openapi-location` | Update | Wrong file path |

Apply with: `/memory-write apply the cleanup actions from the audit`

Notes

  • /memory-propose and /memory-cleanup are read-only. No Serena writes happen until /memory-write is called explicitly.
  • The find_symbol and get_symbols_overview Serena calls in /memory-write and /memory-cleanup are not optional — they are the ground-truth check that prevents writing or retaining incorrect facts.
  • Memories in recurring-pitfalls/ should reference the commit or PR that introduced the issue so cleanup can confirm whether it has been resolved.
  • Run /memory-cleanup at the start of a new quarter or after any significant refactor to prevent stale memories from misleading future agents.