# Activity Log System

A small cross-session continuity system for Claude Code, Codex, or any agent that can read your workspace files.

AI sessions are short-lived. Projects are not. This workflow gives a project a plain-Markdown memory so a future session can see what changed, why it changed, and where to resume.

## Core Model

- `ACTIVITY_LOG.md` keeps the durable history.
- `CONTEXT.md` keeps the compact session-start snapshot.
- Hooks record a deduplicated trail of edited files and lightweight checkpoints.
- A Stop hook refreshes `CONTEXT.md` beside the nearest existing activity log.
- Agent instructions ask the agent to add narrative milestones after substantive work.

The hooks tell you what changed. Narrative milestones explain why it changed.

## Files

```text
<workspace>/
  ACTIVITY_LOG.md
  CONTEXT.md
  tools/activity-log/
    activity_logger.py
    MILESTONE_TEMPLATE.md
    AGENTS_SNIPPET.md
  .claude/settings.json
  .codex/hooks.json
```

The workspace root log covers broad work by default. For a repo or project that needs its own history, initialize a project log:

```bash
python3 tools/activity-log/activity_logger.py init --path "/path/to/workspace/projects/example-project"
```

After that, edits under that project route to the nearest project `ACTIVITY_LOG.md`, and the Stop hook refreshes the neighboring `CONTEXT.md`.

## Agent Instruction Snippet

Add a version of this to your `AGENTS.md`, `CLAUDE.md`, or equivalent agent instruction file.

```md
## Workspace Activity Log

Use `ACTIVITY_LOG.md` and `CONTEXT.md` as local continuity files for substantive multi-session work.

- At session start, read the nearest `CONTEXT.md` when it exists. Fall back to the nearest `ACTIVITY_LOG.md` only when no context snapshot exists or when deeper history is needed.
- Add a narrative milestone when work produces a meaningful decision, reusable workflow, shipped output, or lesson that a future session should be able to reconstruct.
- Use project-specific `ACTIVITY_LOG.md` files as the detailed source of truth for repo or project work. The workspace root `ACTIVITY_LOG.md` is the fallback for broad workspace work and files outside opted-in project folders.
- Do not add secrets, PII, transcripts, or duplicated deliverable content.
- Hooks append a lightweight edited-file trail automatically to the nearest existing `ACTIVITY_LOG.md`. Agent-written notes should capture the reasoning and next step that mechanical logging cannot.
- The shared Stop hook refreshes `CONTEXT.md` beside the chosen log. Treat `CONTEXT.md` as an overwritten session handoff snapshot, not as history.
- New project logs are opt-in. To scaffold one, run `python3 tools/activity-log/activity_logger.py init --path <project-folder>`.
- Record only resources that materially affected the work. Do not inventory every terminal command, passive site visit, or incidental tool call.

Use `tools/activity-log/MILESTONE_TEMPLATE.md` for narrative entries.
```

## Narrative Milestone Template

Use this when work produces a meaningful decision, reusable workflow, shipped output, or lesson.

```md
### HH:MM - <short milestone title>

**Goal:** What the work was trying to achieve.

**Completed:** What changed or shipped.

**Decisions:** Choices made and why.

**Process:** Important steps and iterations.

**Resources used:**
- **Skills:** Material skills used, or `None`.
- **Agents:** Material agents or agent roles used, or `None`.
- **Tools:** Material tools used, or `None`.
- **Apps / sites:** Material apps or sites used, or `None`.
- **Automations / hooks:** Material automations or hooks used, or `None`.
- **Prompts:** Material reusable prompts used, or `None`.

**Dead ends:** What did not work and why, or `None`.

**Files:** Key source files or outputs.

**Verification:** How the result was checked.

**Next:** The next useful step.

**Story notes:** Lessons, surprises, or moments worth revisiting in an article, retrospective, or reusable workflow.
```

## What Not To Log

- Secrets, tokens, or credentials.
- PII or raw participant data.
- Full transcripts.
- Duplicated deliverable content.
- Every incidental tool call.
- Passive site visits that did not materially affect the work.

The log should answer: what changed, what was decided, and what happens next.

## What This Does Not Do

- It does not send data to an external service.
- It does not record full transcripts.
- It does not overwrite an existing `ACTIVITY_LOG.md`.
- It does not overwrite an existing `CONTEXT.md`.
- It does not edit `AGENTS.md` automatically.
- It does not generate automatic transcript summaries.

The edit trail is the automated baseline. The useful memory still comes from the narrative milestones.