Persistent Agent Memory

Persistent Agent Memory is Groove's 7th coordination layer. It persists what agents learn across sessions, rotations, and restarts — so agent #50 on your project knows what agents #1 through #49 figured out.

Why It Exists

Every agent before Groove started from scratch. Different instance, different rotation, different day — same blank slate. If agent bk-3 discovered that "npm install fails unless NODE_OPTIONS is set," agent bk-4 had to rediscover it an hour later. Multiplied across months of work, that's a staggering amount of re-learning.

Groove's memory layer turns those discoveries into project property. Once something's been figured out on your codebase, it stays figured out.

What Gets Stored

All memory lives in .groove/memory/ (gitignored — private to your local project state). Four file types:

1. Project Constraints — project-constraints.md

Hard rules agents have discovered or you've explicitly set. Examples:

• "Never modify packages/daemon/index.js during a live session — restart kills all agents"
• "ESM only — never use require(), always import"
• "Tests must hit a real database, mocked tests masked a broken migration last quarter"

Max 50 entries, hash-deduplicated so the same rule can't get added twice.

2. Handoff Chains — handoff-chain/<role>.md

The last 10 rotation briefs for each role, newest first. When a backend agent rotates, its handoff brief is archived here. When the next backend agent rotates, it gets the last 3 briefs prepended into its new handoff — so there's a causal chain of what each predecessor struggled with and solved.

3. Discoveries — agent-discoveries.jsonl

Error→fix pairs. When an agent hits an error and resolves it successfully, the trigger and fix are written to a shared knowledge base other agents inherit. Successful outcomes only — failed fixes don't pollute the record. Deduplicated by hash. Capped at 1,000 entries with oldest-first pruning.

4. Specializations — agent-specializations.json

Per-agent and per-role quality profiles: session counts, average quality scores, file-touch patterns, preferred rotation thresholds. Used to gate future rotations (converged profiles get a looser quality floor) and surface per-agent strengths.

How Agents Use It

On every spawn, the Introducer injects a Project Memory section into the new agent's context. It contains:

• Active constraints (up to 4K chars)
• The last 3 rotations from the agent's role-specific handoff chain (up to 4K chars)
• The last 20 known error→fix discoveries for the agent's role (up to 4K chars)

The agent sees this like any other context and acts on it — before touching the codebase, it knows the rules, the history, and the common gotchas.

How Memory Gets Written

Three write paths, all automatic:

1. On rotation — the Rotator appends the outgoing agent's handoff brief to the role chain and updates that agent's specialization profile
2. On agent completion — the Process Manager updates the specialization with final-session stats (quality score, file touches, tool call signals)
3. Explicit agent contribution — agents can POST /api/memory/discoveries when they solve something new, or POST /api/memory/constraints when they discover a rule worth preserving

Viewing and Managing Memory

Open the Dashboard → Intel Panel → Memory tab in the GUI to see:

• Hero stats: constraints / discoveries / role chains / specializations counts
• Full constraint list with category pills
• Last 8 discoveries with trigger + fix + role + timestamp
• Active role chains (which roles have handoff history)
• Per-role quality profiles with session counts and average scores

API endpoints for programmatic access are documented at API Reference → Memory.

Cost

Writing to memory is free — it's flat files on your local disk. Reading during spawn adds up to 12K chars to the intro context, which is a one-time token cost per agent spawn that more than pays for itself the first time the new agent avoids rediscovering a solved problem.

Design Principles

• Flat files, not a database. Markdown and JSONL. Grep-friendly, human-readable, git-diffable.
• No vector store. No embeddings, no semantic search. The structure (per-role chains, per-role discoveries) does the filtering.
• No cross-project sharing. Memory is scoped to the project's .groove/ directory. Your company's constraints don't leak into your side project.
• Success-only for discoveries. Failed attempts are noise. Only confirmed fixes get stored.
• Size-capped everything. Constraints (50), chains (10 per role), discoveries (1,000) all have hard caps with sensible pruning so memory doesn't grow unbounded.

Future Evolution

Planned extensions (not yet shipped):

• GUI editing — add/remove constraints directly from the dashboard
• Cross-project patterns — aggregate "always true on this user's machines" rules
• Auto-detection — Journalist synthesis could pattern-match agent output for DO NOT / always / never statements and suggest constraints
• Fine-tuning data export — the discoveries JSONL is a natural format for training a project-specific classifier

The current design is deliberately minimal so these can land as additions, not rewrites.