Session Recovery Project Memory

Session Recovery & Project Memory

Use this skill to make the repository the durable source of project context. Run it before planning, implementation, analysis, or review whenever session continuity matters.

Hard Rules

• Resolve the current repository before reading sessions.
• Never mix sessions from different repositories.
• Load .codex/ project memory before inferring history from transcripts.
• Prefer current repository state over saved memory when they conflict.
• Never expose full conversation transcripts; show concise previews only.
• Never invent unsupported Codex terminal commands. Detect installed commands from local help output before telling the user what to run.
• Append session history; do not overwrite previous entries.
• Update only affected memory sections. Preserve valid older context.
• Never store assumptions as facts. Cross-check against the current repo.

Startup Workflow

1. Detect the repository root.
2. Initialize .codex/ memory files if missing.
3. Read project memory files in this order: project-memory.md, architecture.md, coding-decisions.md, pending-work.md, session-history.md.
4. Search local Codex sessions belonging to the detected repository.
5. Sort candidates by most recent activity, highest activity, then most complete status.
6. Recommend the most recent relevant session.
7. Display additional recent sessions with concise previews.
8. Ask: Which session would you like me to summarize and restore?
9. Accept session number, session name, or session ID.
10. After selection, detect supported local Codex resume/history commands and instruct the user to run only commands verified by local help output.
11. When a summary becomes available, recover project goals, architecture, code changes, security work, technical decisions, and remaining work.
12. At the end of the session, update .codex/ incrementally.

Repository Detection

Find the repository root using .git first, then walk upward looking for project indicators such as package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, composer.json, *.sln, or workspace configuration.

Use the helper when useful:

python3 /home/tintas/.codex/skills/session-recovery-project-memory/scripts/project_memory.py root

If no root can be resolved, use the current working directory as a temporary root and state that repository identity is uncertain.

Project Memory

The repository memory directory is:

<repo>/.codex/

Required files:

.codex/
├── project-memory.md
├── architecture.md
├── coding-decisions.md
├── session-history.md
├── pending-work.md
└── references/

Initialize missing files with:

python3 /home/tintas/.codex/skills/session-recovery-project-memory/scripts/project_memory.py init

Read references/project-memory-files.md before creating or updating these files.

Session Discovery

Search only sessions that belong to the detected repository. Check memory summaries first if available, then raw local Codex storage:

• ~/.codex/session_index.jsonl
• ~/.codex/history.jsonl
• ~/.codex/sessions/
• ~/.codex/archived_sessions/
• ~/.codex/memories/rollout_summaries/

The index can lag; raw JSONL session files and archive files are often more reliable for latest-session recovery.

Use the helper for an initial inventory:

python3 /home/tintas/.codex/skills/session-recovery-project-memory/scripts/session_inventory.py --repo "$(python3 /home/tintas/.codex/skills/session-recovery-project-memory/scripts/project_memory.py root)"

Read references/session-recovery-workflow.md for the exact display fields, preview rules, conflict handling, and command-detection process.

What To Display

Recommended session:

• Session name.
• Session ID.
• Last activity.
• Files modified.
• Brief summary.
• Current status.

Additional recent sessions:

• Name.
• Date.
• Repository.
• Branch.
• Number of interactions.
• Conversation preview.
• Brief description.

Conversation previews must include only the primary objective, major features, bugs fixed, architecture changes, and remaining work. Do not paste the full conversation.

Context Recovery

When a selected session summary is available, recover:

• Project goals and current milestone.
• Architecture, folder structure, patterns, and design decisions.
• Files created, modified, removed, APIs added, and database changes.
• Security work: authentication, authorization, validation, secrets, and infrastructure.
• Technical decisions: libraries introduced, dependencies removed, refactors, and performance improvements.
• Remaining work: TODOs, known bugs, planned refactors, open questions, and next tasks.

Merge multiple selected sessions chronologically and highlight conflicts.

Conflict priority:

1. Current repository state.
2. Explicit user instructions.
3. Most recent session.
4. Existing project memory.
5. Older sessions.

End-Of-Session Update

Before finishing a session that changed understanding or code, update .codex/ incrementally:

• project-memory.md: concise overview, milestone, architecture, technologies, conventions, and constraints.
• architecture.md: diagrams in Markdown, folder structure, module responsibilities, service relationships, and design principles.
• coding-decisions.md: append or update ADR-style decisions with date, context, decision, justification, alternatives, and consequences.
• pending-work.md: TODOs, bugs, refactors, technical debt, and planned features grouped by priority.
• session-history.md: append one entry with session title, date, goal, files modified, summary, decisions, and remaining work.

Use the append helper when useful:

python3 /home/tintas/.codex/skills/session-recovery-project-memory/scripts/project_memory.py append-session --title "Session title" --goal "Goal" --summary "Summary"

Missing History

If no previous sessions exist, initialize .codex/, create the memory files from the current repository state, and state that no prior local Codex history was found for the detected repository.