# Session Recovery Project Memory

> Use this skill at the beginning of a Codex session, and whenever the user asks to resume, continue, recover context, inspect previous sessions, restore a Codex conversation, initialize project memory, update project memory, or preserve architectural decisions and pending work across sessions. It detects the current repository, loads repository-local `.codex/` memory first, searches only relevant local Codex sessions for that repository, recommends the most recent session, supports user-selected session recovery, and updates persistent project memory files without mixing unrelated repositories.

- Skill: `just1cup/session-recovery-project-memory` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add just1cup/session-recovery-project-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/just1cup/session-recovery-project-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Just1cup (https://skillmd.com/u/just1cup)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/just1cup/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:

```bash
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:

```text
<repo>/.codex/
```

Required files:

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

Initialize missing files with:

```bash
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:

```bash
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:

```bash
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.