project-memory

name	project-memory
description	Maintain low-token project memory for large codebases and long-running implementation work. Use when tasks span many files, days, or sessions; when context may overflow; when work must pause and resume cleanly; when a coding agent would otherwise need to reread long chat history; or when a project needs compact resumability without turning memory into a second giant knowledge base.

Project Memory

Use a small external memory layer instead of relying on long chat history.

This skill is for runtime external memory, not model training. It is inspired by self-summarization workflows, but the implementation is a disciplined file-based operating pattern for large projects.

What this skill is for

Use this skill when:

• work will span multiple sessions or days
• the project is large enough that rereading context is expensive
• an agent needs to pause and resume reliably
• multiple subtasks or modules are active, but not all should be loaded at once
• token budget matters and the default hot path must stay small

Do not use this skill to build a giant project encyclopedia.

Goals

• Preserve continuity across long coding sessions.
• Minimize token overhead.
• Restore only what the current task needs.
• Keep stable knowledge separate from volatile state.
• Prevent summary sprawl from becoming a second context problem.

Non-goals

This skill is not for:

• diary-style journaling
• default loading of full history
• storing giant diffs or raw logs in memory files
• creating memory files for every folder by default
• replacing source code, Git history, or issue trackers

Directory layout

Create this structure at the project root when missing:

project-memory/
  overview.md
  current-state.md
  decisions.md
  open-questions.md
  modules/
  task-log/

File roles

overview.md

Store only durable project facts:

• project purpose
• high-level architecture
• major directories and ownership zones
• stable conventions
• cross-cutting constraints

Do not put session chatter, transient blockers, or detailed history here.

current-state.md

Store the minimum state required to resume work:

• active objective
• current subtask
• files/modules in focus
• current blockers
• next 1-3 actions
• short resume checklist

Keep this short. Target under 200 lines. Overwrite stale details instead of appending endless history. This is the default first read during resume.

decisions.md

Store only important decisions that future work could accidentally undo:

• decision
• reason
• impact

Do not log trivial edits.

open-questions.md

Store unresolved questions that affect implementation direction. Remove, resolve, or mark stale items when resolved.

modules/<name>.md

Create only for modules that are large, active, complex, or repeatedly revisited. Store:

• module purpose
• important files
• local constraints
• active risks
• current module-specific next steps

Do not create module files for every folder by default.

task-log/*.md

Use as archive for major sessions or milestones only. This is archival memory, not hot context. Do not read task logs by default during resume. Read them only when tracing history, reconstructing reasoning, or recovering after a long pause.

Module-file creation heuristics

Create a module file only if at least one of these is true:

• the module has enough complexity that you will likely forget key local constraints
• the module is active across multiple sessions
• the module has risky or non-obvious behavior that future work could break
• multiple files must be mentally grouped to work efficiently
• the same module keeps coming back in related tasks

Skip creating a module file when:

• the work is one-file or one-fix only
• the module is simple enough to rediscover cheaply
• the information belongs in current-state.md instead
• the module would just duplicate code structure without adding useful working memory

Resume protocol

At the start of work:

1. Read project-memory/current-state.md.
2. Read only the module file(s) directly relevant to the task, if any.
3. Read project-memory/decisions.md only if the task could touch prior architectural or implementation choices.
4. Read project-memory/overview.md only when project shape is unclear or the task is cross-cutting.
5. Do not read task logs unless needed for forensic context.

Prefer the smallest sufficient read set.

Update protocol

Update memory only at these moments:

• end of session
• before switching to a different subtask or module
• after a meaningful architectural or implementation decision
• when a blocker changes the plan

Do not update memory after every small edit.

Compression rules

When writing summaries:

• use bullets, not long prose
• name exact files or modules
• capture why, not every command
• keep only facts needed for future execution
• replace stale state rather than append duplicates

Prefer distilled state over narration.

Default operating mode

Prefer this loading order:

1. current-state.md
2. one or two relevant modules/*.md
3. decisions.md if needed
4. overview.md if needed
5. task logs only as a last resort

Treat token budget as a constraint. Compact first, expand only on demand.

Real-world usage pattern

A good normal loop is:

1. initialize project-memory/ once
2. fill overview.md lightly
3. keep current-state.md current
4. create module files only when repeated work justifies them
5. write a task log only at a milestone or meaningful checkpoint
6. on resume, read the smallest useful subset only

A bad loop is:

1. create many module files up front
2. append long summaries after every tiny step
3. read every memory file every session
4. keep historical detail in the hot path

Lightweight hygiene / rotation

Use light cleanup rules instead of heavy compaction:

• if current-state.md grows stale or long, rewrite it instead of appending
• if a module is no longer active, keep its file but stop loading it by default
• if task logs become numerous, keep them archival and off the hot path
• if a task log no longer provides unique value, summarize its lasting lesson into decisions.md or a module file and leave the log untouched or archive it externally

Do not build recursive "summaries of summaries".

Portability rules

This skill must work across machines and workspaces.

Therefore:

• prefer relative paths in examples
• do not assume the original workspace or machine still exists
• treat project-memory/ as project-root-local runtime state
• keep templates generic enough to work across repos
• avoid references that only make sense in one codebase

Initialization protocol

If project-memory/ does not exist:

• create the directory structure
• create all core files with short templates
• leave modules/ and task-log/ empty until needed

Use:

• scripts/init_project_memory.py to initialize the runtime directory
• scripts/new_session_summary.py to create a milestone task log when needed
• references/operating-protocol.md as the day-to-day usage contract

Session summary template

For milestone logs in task-log/ use:

# <date> <task>

## Objective
- 

## Completed
- 

## Files Changed
- `path/to/file`: what changed and why

## Decisions
- decision — reason / impact

## Open Issues
- 

## Next Actions
- 

## Resume Reads
- `project-memory/current-state.md`
- `project-memory/modules/<name>.md`

Anti-patterns

Avoid these mistakes:

• default-reading all history
• storing raw terminal logs in memory files
• using task logs as hot context
• creating module memory for every folder automatically
• duplicating the same facts across overview, current-state, and module files
• optimizing for completeness over token discipline

Validation checklist

A good project-memory setup should satisfy most of these:

• resume works after a pause without rereading long chat history
• current-state.md stays short
• only 1-2 module files are usually needed per task
• decisions are recorded without bloating the hot path
• task logs exist, but are rarely needed during normal execution
• token overhead stays low enough that memory helps more than it costs

Source

Refined from the existing project-memory MVP and handoff in this workspace. Primary intent preserved: smallest sufficient read set, stable vs volatile separation, and no default loading of long history.