Raw observations: local, append-only session notes and error/fix snippets. Keep private runtime files under .agent-memory/raw/.
Compiled memory: reviewed, structured Markdown under docs/agent-memory/.
Schema and workflows: .pi/teams/agents/, .pi/teams/workflows/, .pi/teams/teams/, .pi/prompts/, and this README define how memory is captured, queried, and used to improve prompts.

Do not store secrets, API keys, customer data, credentials, or full private transcripts. Prefer short, sanitized lessons with enough evidence to reproduce the issue.

Daily Log Format

Daily entries live in docs/agent-memory/daily/YYYY-MM-DD.md when they are safe to share with the project.

# Daily Agent Memory: YYYY-MM-DD

## Sessions

### Session HH:MM - short-title

**Context:** One sentence about the work.

**Manual Prompts Worth Preserving:**
- Prompt or prompt pattern that improved results.

**Errors And Fixes:**
- Symptom:
- Cause:
- Fix:
- Evidence:

**Decisions Made:**
- Decision and rationale.

**Lessons Learned:**
- Stable lesson, not a one-off accident.

**Prompt/Agent Candidates:**
- Candidate update:
- Target file:
- Confidence:

Compiled Knowledge

index.md is the catalog. Read it first.
concepts/ contains stable lessons, preferences, project conventions, and recurring gotchas.
connections/ links multiple concepts or workflows.
qa/ stores useful answers that should compound into future work.
prompt-evolution/ stores proposed prompt and workflow changes before they are applied.
prompt-change-log.md records accepted prompt, agent, and workflow changes.

Automation

The project-local Pi extension lives at .pi/extensions/agent-memory.ts.

It does these things automatically:

injects the reviewed memory index and prompt change log into each agent turn through before_agent_start
records private raw metrics and session snapshots under .agent-memory/raw/
creates a reviewable pending memory candidate under .agent-memory/review/pending/ after each completed agent turn
records provider header latency, agent duration, turn duration, tool counts, prompt submission gaps, and compaction/shutdown events
detects likely agent questions, starts a blocked-on-user wait timer, and stops it on your next interactive prompt
exposes memory and timing commands

Raw metrics and review candidates are intentionally gitignored. They are evidence for later compilation, not reviewed memory.

The extension cannot infer true keystroke-level active typing time from Pi's current public extension events. It records explicit active work blocks plus automatic gap metrics:

activeWorkMs: time between /prompt-start and /prompt-stop, excluding /prompt-pause to /prompt-resume
pauseInclusiveGapMs: time between previous agent completion and next prompt submission
idleExcludedMs: the portion above the 5-minute idle cap
blockedOnUserMs: waiting time between a detected agent question and your next prompt; this is not counted as active user effort
activeAnswerMs: explicit time between /answer-start and /answer-stop while you are composing an answer to an agent question
agentDurationMs: prompt submission to agent_end
turnDurationMs: one LLM/tool turn duration
headerLatencyMs: provider request to HTTP response headers

Use npx @ccusage/pi@latest session and LiteLLM metrics for token/cost and provider-side inference timing.

Commands

Inside Pi:

/memory-status
/memory-capture [note]
/memory-compile [goal]
/memory-review
/memory-show [filename-fragment]
/memory-approve [filename-fragment]
/memory-discard [filename-fragment]
/memory-clear
/prompt-start [label]
/prompt-pause
/prompt-resume
/prompt-stop
/answer-start [label]
/answer-stop
/blocked-status
/time-report
/pi-remember <lesson-or-error-fix>
/pi-memory <question>
/pi-evolve <evidence-or-goal>

/memory-compile captures a private snapshot and then asks Pi to run /pi-evolve against the latest evidence.

After each agent turn, inspect pending candidates:

/memory-review
/memory-show

Approve the latest or matching candidate:

/memory-approve
/memory-approve 20260429T120000Z

Approval moves the candidate to .agent-memory/review/approved/ and launches /pi-evolve so reviewed memory and prompt changes can be proposed. Discard candidates with /memory-discard or clear all pending candidates with /memory-clear.

Use /prompt-start when you begin an active prompting/planning block and /prompt-stop when you finish. Use /prompt-pause before leaving for an extended wait and /prompt-resume when you return.

When the agent asks a question and you need time to compose the answer, use /answer-start before you start thinking/writing and /answer-stop after you send the answer. The extension also starts a blocked-on-user wait timer automatically when the final assistant message looks like a direct question. That wait time stops on your next interactive prompt and is reported separately from active user work time.

/blocked-status shows whether the automatic blocked-on-user timer is currently running. /time-report writes a private report under .agent-memory/reports/.

Guardrails

Memory can suggest prompt changes; it must not silently rewrite prompts.
Prompt changes require a critic/reviewer pass and /team-validate.
Commit prompt changes on a feature branch.
Prefer small, testable prompt changes over broad rewrites.
If a lesson is only true for one feature, store it with that scope.
If evidence is weak, classify it as hypothesis, not rule.