# Memory Policy

## Purpose

This document defines where Harness memory should live.

The short version:

- Shared project decisions and reusable patterns belong in `.claude/memory/`.
- Noisy per-session logs and runtime state belong in local state paths.
- Codex native state stays in `${CODEX_HOME:-~/.codex}` and is not the Harness project memory source of truth.

## Project Memory

Use `.claude/memory/` for durable project knowledge.

| Path | Role | Git policy |
|------|------|------------|
| `.claude/memory/decisions.md` | Important decisions and why they were made | Share when useful |
| `.claude/memory/patterns.md` | Reusable implementation and operation patterns | Share when useful |
| `.claude/memory/session-log.md` | Session handoff notes | Local by default |
| `.claude/memory/context.json` | Project context cache | Local by default |

## Runtime State

Use `.claude/state/` for machine-readable runtime state.

Examples:

- `.claude/state/session.json`
- `.claude/state/agent-trace.jsonl`
- `.claude/state/codex-loop/`
- `.claude/state/advisor/`
- `.claude/state/locks/`

These files are usually local. Commit them only when a specific workflow says they are stable documentation or test fixtures.

## Codex State

Codex native state can live under `${CODEX_HOME:-~/.codex}`.

Do not treat `.Codex/` or `~/.Codex` as canonical Harness paths. The uppercase form is historical drift.

Codex thread / transcript / cache data is useful runtime context, but Harness project decisions should still be promoted into `.claude/memory/decisions.md` or `.claude/memory/patterns.md` when they become durable.

## Session IDs

Session logs should not assume one environment variable exists everywhere.

Resolution order:

1. Claude Code: `${CLAUDE_SESSION_ID}` when present.
2. Codex: runtime-provided session or thread ID when present.
3. Shared fallback: `.claude/state/session.json` field `.session_id`.
4. Last resort: a generated timestamp-based ID.

This keeps Claude and Codex logs traceable without making either runtime the only supported path.