project-memory — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited project-memory (Agent Skill) and scored it 96/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 1 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 1 flagged
The text {match} tells the agent to skip the normal "ask the user first" gate. Used adversarially it removes the human-in-the-loop check before destructive or sensitive actions, turning a normally-gated agent into a fire-and-forget executor.
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
Use this skill when the user wants to preserve, recover, migrate, or audit long-running project or research context across chat loss, model changes, tool handoffs, or multi-session work.
The skill separates current truth, plans, decisions, evidence, hypotheses, human summaries, and recovery checkpoints so that no single chat transcript becomes the source of truth.
Use this skill when the user asks to:
Do not use this skill as a replacement for domain expertise, citations, or source verification. It is a continuity and documentation-routing skill.
The human usually does not write memory files directly. The AI agent is responsible for updating the project memory during the chat or coding session.
Do not rely on tool-internal or session-local memory as the canonical source of truth. Treat repository files as the durable, shared memory layer across Codex, Claude Code, and future tools.
Capture broadly. Promote narrowly.
Do not let hypotheses, plans, or recovery notes silently become truth.
Project memory is not a full-file synchronization system.
Do not read or update every project-memory file on every run. Do not treat the file list or read order as a checklist.
Each piece of information should go to its canonical home. Update only the files whose canonical responsibility changed.
Most work sessions should update only 1-3 files. Larger updates are appropriate only during major transitions, such as phase changes, major hypothesis confirmation or rejection, architecture or approach changes, release checkpoints, or large migrations.
Before editing memory files, produce a short update plan stating:
For a small, obvious one-file update, a one-sentence plan is enough. If you notice you are about to edit memory files without an update plan, stop and produce the plan first.
When one piece of information seems to belong in multiple files, choose one canonical home according to DOCS_GUIDE.md and CONTEXT_MANIFEST.md. Other files may reference the canonical entry, but should not duplicate the full details.
Start with CONTEXT_MANIFEST.md when present.
Do not preemptively read the full memory set. Use the read order as a priority order, not as a checklist.
Before reading additional memory files, identify which files are relevant to the current task. For non-trivial work, briefly state which memory files will be read and which relevant files will not be read.
During a work session, do not wait for the human to explicitly ask for logging.
Do not write to canonical memory files at the first appearance of an idea. Treat new hypotheses, decisions, observations, blockers, risks, and next actions as capture candidates until they stabilize. Keep capture candidates silently during the current session. Do not announce every candidate or repeatedly say that it is being held for later.
Write capture candidates to memory when the topic changes, the discussion reaches a conclusion, the session is ending or may be interrupted, the human explicitly asks to record something, or a decision, result, blocker, or next action becomes clear enough to preserve. After writing, briefly report what was recorded and where.
Capture only material that changes project memory. Do not summarize routine conversation, temporary phrasing, or early ideas that are still being refined.
Use RECOVERY_NOTES.md only as a short resume pointer. Do not make it the source of truth.
project-memory is a skeleton, not a fixed operating system. Customize the profile, capture trigger strength, review cadence, archive policy, and tool-facing instructions to fit the project.
When initializing an empty workspace or adopting an existing project, recommend the smallest sufficient profile before writing memory files:
light: small personal project, short-lived work, or minimal continuitystandard: normal coding, writing, or product work with decisions and next actionsresearch: experiments, evidence, hypotheses, repeated investigation, or debugging loopsacademic: literature, figures, tables, thesis, paper, provenance, or publication-grade traceability workflowRecommend a capture trigger strength alongside the profile:
light: record only explicit requests, session-end checkpoints, and major decisionsstandard: record topic-boundary decisions, next actions, blockers, and direction changesresearch: also record hypotheses, observations, failed attempts, and evidence changesacademic: also record literature, methods, figures, tables, visual assets, provenance, and publication-grade traceabilityDo not default to the largest profile or strongest capture trigger just to be safe. Use the lightest setup that preserves the project's real continuity needs.
Communicate with the user in the user's language by default.
Preserve the repository's dominant language for canonical docs and file names unless the user explicitly asks to change that policy.
If the repository language is unclear or mixed, confirm the canonical documentation language once before writing or translating structured memory files.
If chat language and doc language differ, explain in the chat language and keep the canonical docs in the chosen documentation language.
Route information by status:
| Information type | Canonical file |
|---|---|
| Confirmed current state | CURRENT_STATE.md |
| Future intended work | ROADMAP.md |
| Decisions and rationale | DECISION_LOG.md |
| Research observations, experiments, evidence, results | RESEARCH_LOG.md when present; otherwise route direction-changing findings to DECISION_LOG.md and speculative observations to HYPOTHESIS_LAB.md |
| Unverified ideas and speculative explanations | HYPOTHESIS_LAB.md |
| Human-facing orientation summary | HUMAN_BRIEF.md when present |
| Fast session resume checkpoint | RECOVERY_NOTES.md |
| Compact combined history for the light profile | LOGBOOK.md |
| Prior work, references, and their relevance (academic profile) | LITERATURE_NOTES.md |
| Figures, tables, and visual outputs (academic profile) | FIGURES_LOG.md |
| File roles, read order, ignore rules | CONTEXT_MANIFEST.md and DOCS_GUIDE.md |
The canonical memory lives in version-controlled markdown files in the repository. Tool-specific memory features may help execution, but they must not be treated as the only source of truth.
In an existing project, never overwrite or delete existing project files without explicit user approval. Treat existing same-name files such as README.md, ROADMAP.md, DECISION_LOG.md, AGENTS.md, or CLAUDE.md as user-owned. If a project-memory template path collides with an existing file, place project-memory files under a non-conflicting directory such as memory/ or project-memory/, or record the chosen canonical locations in CONTEXT_MANIFEST.md.
Use:
README.md as the entry point in a new memory workspace; in an existing project, keep the project README user-owned and use CONTEXT_MANIFEST.md to declare canonical memory locationsCURRENT_STATE.md for current trusted assumptionsROADMAP.md for future intended workDECISION_LOG.md for adopted, rejected, or deferred decisionsRESEARCH_LOG.md for tests, investigation, observations, and evidence when the selected profile includes itHYPOTHESIS_LAB.md for unverified ideas and emerging hypothesesHUMAN_BRIEF.md for fast human orientation when the selected profile includes itLOGBOOK.md for compact combined decisions, observations, hypotheses, and notes in the light profileRECOVERY_NOTES.md for restart checkpointsIf the repository also uses AGENTS.md, CLAUDE.md, or similar tool-facing guidance, keep those files short and point them to these canonical docs instead of duplicating project memory there.
When resuming or migrating a project, read in this order unless CONTEXT_MANIFEST.md says otherwise:
This is a priority order for orientation, not a checklist to exhaust on every run. Read only as far as needed to route the current task safely.
CONTEXT_MANIFEST.mdRECOVERY_NOTES.mdHUMAN_BRIEF.md when present, or LOGBOOK.md in the light profileCURRENT_STATE.mdROADMAP.mdDECISION_LOG.mdRESEARCH_LOG.md when presentHYPOTHESIS_LAB.mdDOCS_GUIDE.md when routing or updating docs is unclearIf CONTEXT_MANIFEST.md is missing, use the default read order above and recommend creating one.
Before reading a repository or workspace, avoid obvious noise unless the user specifically asks for it:
.git/, .hg/, .svn/.cache/, cache/, tmp/, .tmp/, __pycache__/logs/, *.log, *.jsonldist/, build/, .next/, target/, node_modules/Use .contextignore if present. If a workspace has many generated files and no ignore policy, recommend adding one.
When updating memory, first classify the new material.
CURRENT_STATE.md whenDo not place untested claims here. If the claim is inferred but not verified, put it in HYPOTHESIS_LAB.md, or in RESEARCH_LOG.md with uncertainty when that file exists.
ROADMAP.md whenA roadmap item is intent, not proof.
DECISION_LOG.md whenEach decision should include context, alternatives, rationale, risks, and revisit conditions.
RESEARCH_LOG.md when presentKeep methods, inputs, results, interpretation, confidence, and limitations together.
If RESEARCH_LOG.md is not in the selected profile, record direction-changing findings in DECISION_LOG.md and keep still-speculative observations in HYPOTHESIS_LAB.md.
HYPOTHESIS_LAB.md whenStructure HYPOTHESIS_LAB.md into:
#### Raw sparks Low-commitment captures. These may be vague, incomplete, or speculative.
#### Working hypotheses Ideas that have recurring relevance, clearer structure, or a defined next step.
Do not require the human to explicitly ask for logging. Prefer over-capturing in HYPOTHESIS_LAB.md over losing potentially valuable ideas.
HYPOTHESIS_LAB.mdCapture broadly. Delete cautiously.
Do not silently delete hypotheses or raw sparks from HYPOTHESIS_LAB.md.
When cleanup is useful, produce a review list first and group candidates by suggested action:
The human must approve deletions and major merges before files are modified.
Raw sparks may be deleted after approval. Working hypotheses should usually be marked as dropped with a short reason rather than erased.
HUMAN_BRIEF.md whenReview HUMAN_BRIEF.md when any of the following occur, and update it only if the human-facing picture changed:
DECISION_LOG.md entry changes direction, priority, risk, tracked threads, or required human decisionsROADMAP.mdCURRENT_STATE.mdRESEARCH_LOG.md entry changes confidence in a key assumption, when that file existsRECOVERY_NOTES.md checkpoint changes the current goal, main blocker, next decision, or tracked thread statusWhen updating, keep HUMAN_BRIEF.md short. It should summarize what matters for human judgment, not duplicate proof, history, or detailed methods.
At the top, maintain ## Tracked threads so parallel work is visible at a glance. Each thread should state: name, status, next action or blocker, and the canonical source file.
This file is a summary layer, not the canonical proof layer.
LITERATURE_NOTES.md whenHYPOTHESIS_LAB.mdEach entry should connect the source to this project's hypotheses, methods, or decisions. Do not just list references — explain relevance.
This file is used in the academic profile. If the profile is research or lower and this file does not exist, do not create it unless the user is working toward a publication.
FIGURES_LOG.md whenWhen a visual file exists, is generated, or is provided by the user, save a durable copy under the project's figure asset directory before relying on it. The default directory is figures/ unless CONTEXT_MANIFEST.md declares another path.
Use stable figure IDs for filenames, such as figures/FIG-001.png, figures/FIG-001-source.png, or figures/FIG-001-final.svg. If the asset is not yet a formal figure, save it under figures/inbox/, for example figures/inbox/IMG-YYYY-MM-DD-001.png, and promote or link it to a FIG-xxx path later.
Each entry should link the visual asset path to its original source, data source, and generation method so it can be found, reproduced, or revised during peer review. Preserve the original supplied image when a processed, cropped, annotated, or regenerated version is created.
This file is used in the academic profile. If the profile is research or lower and this file does not exist, do not create it unless the user is managing visual outputs for a publication.
RECOVERY_NOTES.md whenKeep this short and newest-first. It should answer: what changed, what is true now, what is blocked, what to do next, and which canonical docs to trust.
When files disagree, do not silently merge them.
Use this priority order for current-state questions:
CURRENT_STATE.mdDECISION_LOG.mdRESEARCH_LOG.md, when presentRECOVERY_NOTES.mdHUMAN_BRIEF.md when presentROADMAP.md when presentHYPOTHESIS_LAB.md when present, or LOGBOOK.md in the light profileThen report the conflict and propose a patch.
Important distinctions:
CURRENT_STATE.md describes what is true now.DECISION_LOG.md explains why a choice was made.RESEARCH_LOG.md records evidence and interpretation in research-oriented profiles.ROADMAP.md says what is planned.HYPOTHESIS_LAB.md is never truth by itself.LOGBOOK.md carries lightweight history in the light profile.RECOVERY_NOTES.md tells where to resume but is not the full source of truth.Do not promote anything directly from HYPOTHESIS_LAB.md to CURRENT_STATE.md.
Promotion to CURRENT_STATE.md requires at least one of:
RESEARCH_LOG.md when presentDECISION_LOG.mdDECISION_LOG.md when the selected profile does not include RESEARCH_LOG.mdOnly promote an item to CURRENT_STATE.md when all of the following are true:
revisit_when conditionWhen promoting, update the hypothesis status to promoted and link the new canonical location.
CURRENT_STATE.mdDivide CURRENT_STATE.md into:
Things supported by evidence and safe to treat as current truth.
Current workflow rules or adopted operating assumptions.
Current priority, major blocker, and near-term direction. These may change more often and should be reviewed regularly.
Choose the mode that matches the user’s task.
Use when the workspace has just been created and all canonical files are empty templates. See tasks/init_session.md for the full process.
Detect init state: CURRENT_STATE.md contains only template placeholders, RECOVERY_NOTES.md has no project-specific checkpoint or only the generated initial checkpoint, and HUMAN_BRIEF.md has no project-specific summary when that file exists.
Before writing files, recommend and confirm the smallest sufficient profile and capture trigger strength.
Ask four questions: project purpose, current stage, immediate goal, known constraints or decisions. Write answers into the canonical files present for the selected profile: always CURRENT_STATE.md and RECOVERY_NOTES.md; also ROADMAP.md, DECISION_LOG.md, and HUMAN_BRIEF.md when present. Leave other files empty until content arises naturally.
Return a summary of what was written and where.
Use when introducing project-memory into an existing project that has code, documents, or history but no structured memory workspace. See tasks/adopt_existing.md for the full process.
Detect adopt state: project directory has working files but no CONTEXT_MANIFEST.md or CURRENT_STATE.md.
Inventory existing docs, README, git log, and user knowledge. Detect the dominant repository language and preserve it for canonical docs unless the user asks otherwise. If the repo language is unclear or mixed, confirm the documentation language once before writing structured memory files. Recommend a profile and capture trigger strength based on the project shape. Classify each piece of information by type and route it to the correct canonical file. Do not overwrite existing same-name project files; choose non-conflicting locations and record them in CONTEXT_MANIFEST.md. If AGENTS.md or CLAUDE.md exists, point it to CONTEXT_MANIFEST.md instead of duplicating memory there.
Return a summary of sources inventoried, classification results, and gaps.
Return:
Return either:
Return:
Evaluate:
CURRENT_STATE.mdHUMAN_BRIEF.md when presentAt meaningful stopping points, the AI should:
RECOVERY_NOTES.mdHYPOTHESIS_LAB.mdDECISION_LOG.md if a decision was madeRESEARCH_LOG.md if that file exists and research or testing occurred; otherwise record direction-changing findings in DECISION_LOG.mdCURRENT_STATE.md changedHUMAN_BRIEF.md needs refresh when presentDo not duplicate the same content across files unless a short summary is necessary for navigation.
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.