# Agent Memory And Tracking State

## Principle

Agents may remember freely in local session files, but they should only promote
carefully into committed project memory.

Use JSON as the canonical format for shared agent state. Use JSONL for
append-only event streams. Markdown may be generated later as a human export,
but it should not be the canonical agent state format.

## Storage Tiers

| Tier | Path | Git | Purpose |
| --- | --- | --- | --- |
| Project state | `.prd_plugin/state/*.json` | committed | Shared project memory, tracking, decisions, and changelog indexes. |
| Tracking branches | `.prd_plugin/state/tracking-branches/DBR-*.json` | committed | One assigned worker's proposed tracking delta; promoted serially by the lead. |
| Promoted sessions | `.prd_plugin/state/sessions/shared/*.jsonl` | committed | Concise source-backed session summaries that future agents should see. |
| Local sessions | `.prd_plugin/local/sessions/*` | ignored | Raw events, scratch state, handoffs, and temporary observations. |
| Formal artifacts | `docs/**` | committed | Human-readable PRDs, architecture, plans, evidence, decisions, and traceability. |

## Recommended Files

```text
.prd_plugin/
  state/
    project.json
    memory.json
    decisions.json
    changelog.json
    tracking.json
    tracking-branches/
      DBR-001.json
    requests.json
    health.json
    sessions/
      shared/
        promoted-session-summaries.jsonl
  local/
    sessions/
      <session-id>/
        session.json
        events.jsonl
        scratch.json
        handoff.json
```

## Promotion Rule

Raw session memory is local by default. Promote only records that are:

- concise
- source-backed
- non-sensitive
- useful beyond the current session
- linked to project artifacts or file anchors where possible

Never promote secrets, credentials, private prompts, chain-of-thought-like
reasoning traces, unreviewed tool dumps, or user-specific local context.

For parallel worktrees, the lead calls `prd_open_tracking_branch` before
fan-out and launches each worker with `PRD_WORKER_SESSION=1`,
`PRD_TRACKING_BRANCH_ID=<DBR-*>`, and `PRD_TRACKING_BRANCH_OWNER=<owner>`.
Workers call only `prd_update_tracking_branch` on their assigned file;
they do not edit canonical state or the registry. Once worker branches are
merged, the lead calls `prd_promote_tracking_branch` serially. Canonical IDs are
allocated only during promotion, and repeated promotion returns the existing
result instead of creating a duplicate.
Use `prd_status`, `prd_find(kind: DBR)`, or `prd_get(DBR-*)` to recover branch
ownership and state after a crash or handoff instead of scanning branch files.

## Cascading Authority

1. Local session files capture raw working memory.
2. Agent/session summaries propose durable facts or handoffs.
3. Committed project state records promoted operational memory.
4. Formal docs and evidence remain the project truth for requirements,
   architecture, implementation, and claims.

Health findings in `.prd_plugin/state/health.json` are operational warnings
about this graph. They should cite affected records and should not become a
second source of truth.

Request records in `.prd_plugin/state/requests.json` are an intake queue for
proposed changes. They are not accepted work until reviewed and linked to
tracking, document branches, requirements, or changelog records.

Request and message state is repo-scoped. The `prd-plugin` repo can be the
upstream hub for plugin-level intake, but downstream repos should keep only
their own local requests and messages unless they explicitly submit a sanitized
record upstream. Do not index or submit `.prd_plugin/local/`.

Request discussions belong in `thread.messages` using `MSG-*` IDs. Promote only
sanitized, visibility-appropriate messages upstream; keep private local
discussion, raw session paths, and local-only evidence in the downstream repo.
When promoting request memory, check for an existing `REQ-*` thread first;
persistent bugs and repeated repros become new `MSG-*` entries on that thread.

Cross-repo request exchange uses mailbox files, not direct repo writes.
Downstream repos export sanitized packages from `.prd_plugin/outbox/`, the hub
stages them in `.prd_plugin/inbox/`, and downstream repos pull only their own
scoped `.prd_plugin/mailboxes/<repo-id>/` bundle.

## Provenance Fields

Promoted memory records should include:

- stable ID
- record type
- claim or summary
- source references
- originating session ID
- originating agent ID
- linked observation IDs, when promoted from observations
- confidence
- status
- timestamps

Example:

```json
{
  "id": "MEM-001",
  "type": "repo_fact",
  "claim": "The plugin ships skills, method docs, templates, and helper scripts for downstream diagnostics and repo-local skill installation.",
  "source_refs": ["README.md", ".codex-plugin/plugin.json", "scripts/prd_install_skills.py"],
  "source_observations": ["OBS-001"],
  "created_from_session": "SES-001",
  "created_by_agent": "AGENT-001",
  "confidence": "high",
  "status": "active",
  "created_at": "2026-06-13T09:04:00Z"
}
```

Use human-readable labels in addition to IDs when helpful, but keep `AGENT-*`
and `SES-*` as the traceability keys.