Context Memory
Context/ is the project's memory: what it knows that is not code, as plans, research, decisions, rationale, status, schedules, references, and records. It is project knowledge, not a second instruction hierarchy.
Topical documents state facts, opinions, constraints, decisions, and plans directly. Rules that govern how an agent works across tasks, including how the user wants to be worked with, belong in the nearest applicable AGENTS.md, where every session loads them. They do not go in a topical document, in the authored part of Context/AGENTS.md, or in a harness memory store. A plan, checklist, decision, or runbook may still contain instructions when those instructions are the subject of the document.
Where This Skill Applies
This skill governs a project when a Context/ directory in this format already exists there, when the user asks for one, or when the project's instructions call for one, whatever file carries them. Being installed is not one of those signals: availability in a catalog, a global skills folder, or a remote library does not make the skill apply, and a project with none of these signals keeps whatever it already uses.
Precedence Over Built-In Memory
Where this skill applies, Context/ is the durable store for project knowledge and it supersedes any memory feature the harness provides. Do not write project knowledge into those. When a harness memory store already holds some, migrate each fact into its owning Context document and leave the harness store empty.
This governs durable project knowledge only. A preference that spans unrelated projects is not project knowledge, and this skill keeps no store for it. Write it as a rule in the AGENTS.md of each project where it applies.
Reading
The index in Context/AGENTS.md lists every active document with when to read it. When it is already in your context, do not read the file again. Otherwise read it first. Open only the documents whose paths and descriptions match the task, and search within the relevant topic when more than one owner is plausible. Looking something up needs nothing else from this skill and no generator run.
Building an agenda, schedule, reminder list, or any list of what is open, owed, or waiting for the user is more than a lookup, whether it comes from Context, a sweep of messages, or the session's own earlier replies. Build it fresh each time it is reported, never carried forward. Before an item goes on, check:
- The messages, mail, and invitations the session can reach that are newer than the source the item rests on.
- Evidence that it was done, such as sent mail, receipts, shipment records, or files, of any date.
- The decisions made since, this turn's included.
- Whether it belongs to another project.
A passed date or event starts the check and settles nothing either way: a plan whose date has passed is not done until something shows it happened. Leave off an item that is done, answered, made moot by a decision, never owed, or past with nothing left to do, and correct what Context still states about it. Do not mention what was left off, not even as a list of what is already done. An overdue item that still needs action stays on, and one the session cannot settle stays on worded as unconfirmed, never as done, missed, or unpaid. An item that belongs to another project goes to that project as Filing says. A disagreement between records about something past that changes no decision or next step is not raised and not recorded as unresolved, and dated records stay as written. Ask the user only when what the session can reach leaves an item undecided.
Capture
Write project knowledge into its owning document in the same turn, unasked, whether it comes from the user, the work, or a source. Saying it once is the request, and nobody has to say save, note, or remember. Preserve what affects how the work continues or would otherwise need rediscovery:
- Decisions, preferences, opinions, and constraints, with their reasons, and confirmed approaches recorded as readily as changed ones.
- Other people's commitments, availability, and progress, as readily as the user's own: what someone promised, when they are away or busy, what they are behind on.
- Asides and maybes about later work, however briefly said, recorded as open in the speaker's words.
- Rules for how to work with the user, written to the nearest applicable
AGENTS.md in the turn they are given, even when that turn changes nothing else.
- Plans and next steps, with their timing and dependencies.
- Changes in the state of the work: what is done, what is waiting and on whom, what is due, and where anything made outside the repository lives.
- Discoveries from the work or a source, with a reference where it supports later verification.
State what is true now. When the user or a source corrects or changes something, rewrite the owning statement so the document reads as if it had always been right, and remove the old value from every active document that states it as current. Reconcile what depended on the old value as this section's rule for a changed state, decision, or plan says, and where its new value is not known, mark it unconfirmed without citing the old value. Do not record the correction as an event, and do not keep the old value beside the new one. Keep an earlier value only when a later reader needs the history itself, such as the reason a plan moved, and leave dated records and archived text as they were written. In a Git repository, history holds what a document said before.
A source that states a new value as now in force for something Context holds, such as the date, time, or place of an event, corrects it even when the user says nothing, so the old statement is edited, never joined by a second entry. An offer, a quote, or an option is not such a value until the user, or whoever sets the fact, accepts it. When the user sets the fact, their word corrects it and is not ranked. Between sources that disagree, the written word of whoever sets the fact outranks a relayed or spoken figure, and a later message outranks an earlier one from the same sender. Write the winner and remove the loser. When the outranked source is the newer one, or no ranking settles it, write neither as settled: record the fact as unresolved, name who can settle it if a source names them, and give any plan made in the meantime the event that ends it.
Capture what the work established rather than narrating the turn. A log belongs in Context when its history is useful later in its own right, such as a record of runs, submissions, or contacts. When an event recurs, or the user says how to handle one, write the rule where the next run will read it, not only the log entry.
Never record a guess as the user's decision. Keep proposals apart from agreed plans, attempts apart from finished work, and inferences apart from confirmed facts. Write a choice as decided only when the user decided it. A tentative remark is recorded as open, in the user's words. A line drawn from a source says only what the source says. A reading of what the user or a source meant is marked as the agent's reading, and an instruction relayed by another agent is attributed to that agent. Name who takes each pending step when the user or a source said who. A step the user said they will take is never left for the next session to take. Attribute to no one a step, follow-up, owner, or date they did not state, and mark a step the agent proposes as its proposal. Before reporting anything saved, match each line written in the turn to what supports it, the words of the user or a source or what the work itself showed, and mark as the agent's reading, or remove, any line that nothing supports. Call the user by a name only when the project's own files give one, never one taken from a skill, a tool, or the machine.
Write a relative date (tomorrow, next week, in two weeks) as the absolute date counted from when it was said or sent, never from when it is filed. A line in a recording was said at the recording's start plus the line's offset, and the time a recording carries may be when it ended rather than when it started, so find which from the project's notes or the tool before counting from it, and when neither says, the time is unknown. Keep the precision given, such as the week of a date, and when the time of the source is unknown, keep the words and mark them unconfirmed. Something due, which someone committed to by a later date or event, is written with that date or event where a session will meet it before then: preferably a document the index says to read at every session start, otherwise the owning document, whose description names that date or event as the Frontmatter section says. A maybe or an idea keeps any timing its speaker gave but is not due.
After a message or source that carries several items, go through all of it, not a summary of it. Filing it is not done until every actionable line in it is captured: what anyone promised, asked for, or advised that implies a step, with that step marked as the agent's reading unless it was said, every date set, what was said to an outsider that a teammate who was not there needs to hear, recorded as something that teammate needs to be told, and a reversal, which updates the earlier item to quote the later line instead of adding a second. Each item keeps its quote in the speaker's exact words and when it was said. It names the owner and due time someone stated, the due time written as an absolute date with a time of day when one was given, or it says that nobody stated them. Check each item against its owning document before reporting it saved. Tell who said or owns each line from what is said and from the project's files, not from labels alone, since speaker labels and display names drift. A turn that ends on a question or a hold still writes what the user decided or asked for in it. When the turn changed Context, run the generator, then end the reply with what was saved, in which document, and from which source, and say when each dated item comes up: its date, and the document a session will meet it in. In that report, an item found done, answered, or moot while checking gets no line of its own, and neither does a past disagreement settled while checking: say only which documents were brought up to date. A turn that adds or changes no such knowledge needs no capture update.
What the work shows in passing is a source too. An email in a result list, a file in a folder, a message preview, or a page opened for something else is captured like any source when it bears on the project and Context does not already hold it, even when it is not the task. Open each item in such a list that might bear on the project, not only the one the task needed, and skip only what plainly does not. An attachment is content even when its message has no text: record who sent it, when, its file name, where it lives, and whether it is saved into the project. The capture report names what was saved besides the task.
Update the owning document rather than adding a duplicate. When a state, decision, or plan changes, search the relevant documents for statements and procedures that depend on it and reconcile them in the same turn, keeping the current fact in one owner and linking to it elsewhere. When a dependent statement cannot stay true with the new value, mark that statement unresolved rather than writing it as settled. Delete what turns out to be wrong. When the user says to remove something, remove it. Record a standing rule against it only if it keeps returning.
Delegation
The session that works with the user owns capture. A worker does not need this skill to do its task. When a worker's task depends on project knowledge, its brief names the Context documents to read, or tells it to start from the index. A worker returns what it learned in its report, and the session that briefed it files that in the same turn. A brief that hands a worker a long source, or a part of one, to read for its items tells it to flag every line that could be actionable, with its quote and time, and to over-flag rather than miss, and the briefing session decides which are items. When a brief does have a worker write to Context, the brief names this skill, and whoever holds the result runs the generator afterwards, so no index is left stale.
Filing
- One current fact has one owner in Context. Other documents link to it, and a decision a README or another project file also shows is still stated in its Context owner.
- Organize by the project's real subjects. Before adding a file, decide which subfolder owns it, and create that subfolder in the same change when the subject has enough files to read as a group. Root-level files are reserved for project-wide owners such as current status or a master plan.
- A status document states the present and is edited in place. An item leaves it in the turn evidence arrives that it is done, answered, or moot. An item whose date or event has passed leaves once nothing is left to do. A durable fact gets an owner of its own before it leaves status, and dated history goes to a log.
- Use Title Case for folders and markup filenames. Name evergreen files for the subject they own, not the temporary task that created them. Prefix time-anchored records with
YYYY-MM-DD , followed by the subject. A date alone is not a name.
- Aim for roughly 4 to 12 active markup files in a directory, and no more than 8 at the root. More than 12 triggers an organization review, and more than 20 means the directory needs clearer subtopics unless it is an intentional chronological or generated collection. Three or four levels of meaningful subdirectories are healthy. Folders are for filing: they give a new fact an obvious home and keep one subject's files together when a subject is renamed, split, or archived.
- File count and description length are the cost paid at every session start, because every active description sits in the index. Document length is paid only by a reader who needs it.
- Write Markdown. A file that is not a document sits in the folder of its subject, beside the document that uses it when there is one, and needs no document of its own. A document that mentions a file links to it.
- Every file in Context is there on purpose: a document, or a file kept for what it is, such as a video, an image, or the source that makes one, whether placed by hand or written there by a script. Context is never a working folder. Installs, caches, intermediate build and scratch output, and temporary downloads go outside Context, such as the session's scratchpad or temp folder. Whatever this task left in Context by accident is removed or moved out before the turn ends.
- Anything the user hands over to be saved, by whatever route, is filed in the form its content needs: text that arrived as a picture becomes text, pieces of one record that were split only by how they arrived become one document, and pieces that are separate on purpose stay separate.
- A fact can belong to another project. Search every project it could belong to before deciding where it goes or saying it was never saved. File it in that project's Context, or in its
Context-Inbox/ when this session may not edit it. Keep it out of this project's Context and out of what this session reports as open here.
- Before moving, renaming, or archiving a document, or filing one out of
Context-Inbox/, the folder beside Context/ where others drop material to be filed, search for its path and its filename across the whole project, not only Context, and in every other project that links into this Context, such as a sibling repository or a parent workspace. In the same change, in active documents, retarget every link, say that an archived target is archived, and correct every statement of where the document is or that it still waits in the inbox. In dated records and archived text, retarget the link only. The move changes no other line in those files, so their diff shows only those edits. A link whose target is gone for good becomes plain text or a code span.
- The authored part of
Context/AGENTS.md, above the generated block, holds this directory's filing conventions only: where a kind of document goes, how it is named, how a recurring source from the inbox is filed. Write one when a convention would otherwise be reinvented, keep it to a few lines, change it when the directory changes, and follow it when filing.
Read the structure reference before creating a Context directory, adding a second one inside a project, moving or closing a project, splitting or merging a document, writing an HTML document, or filing a document that arrives with frontmatter of its own.
Frontmatter
Every active Markdown file begins with:
---
name: <Title Case Document Name>
description: <one line saying what the file holds and when it is useful>
date_created: YYYY-MM-DD
date_modified: YYYY-MM-DD
---
Descriptions are selection metadata. They name what the file holds and when it is useful, on one line, aiming under 200 characters and never over 1024, and they do not summarize the findings. A file that holds something due, other than a document the index says to read at every session start, leads its description with it, in the shape Read by YYYY-MM-DD:, or Read by <event>: when no date is known, inside the same limit, and drops it once nothing is left to do. The body owns the actual information.
name matches the document, date_created is the day the document entered Context and never changes, and date_modified changes when the body's content changes, so it says when the document's knowledge last changed. A move, a rename, a retargeted link, a note that the document was superseded or archived, or an edit to the description alone is not a content change. The date an event happened belongs in the filename prefix and the body, not in these two fields.
When a document records a time of day, write it in RFC 3339 with its UTC offset, in the shape YYYY-MM-DDThh:mm:ss+hh:mm.
The Generator
Run the generator once at the end of a turn that changed active Context. It is one zero-dependency Node script, and both routes below run the same file:
# Skill not on disk (served from a remote library)
npx --yes github:LeeorNahum/context-memory-skill <path-to-Context>
# Skill on disk (a repository .agents/skills install or a global skills folder)
node <skill-root>/scripts/index.mjs <path-to-Context>
Both routes need Node. The remote route also needs npm, Git, and network access.
The generated block lists each active markup file as one bullet: its path, an arrow, and its description. It omits archived material and assets, validates active frontmatter, and preserves authored text outside the guards.
The generator also checks links. It reads every inline Markdown link with a relative target under Context, Archive included. In the other Markdown files of the folder that holds Context it reads only the links that point into this Context or its inbox, because those are the ones a move, an archive, or a drain breaks. --links=<folder> adds any other folder that links in, such as the rest of the project when Context sits in a subfolder, a sibling repository, or a parent workspace, and is remembered for that Context. --check reports without writing anything, for a Context this session is reviewing and not editing, and what it reports goes to the session that owns that Context. --help lists the other flags.
A whole-directory cleanup means an editorial audit, not only index regeneration. When the user asks for an audit, a tidy, a consolidation, or an inbox drain, follow the upkeep reference.
Generator Warnings
The generator's warnings are work, not notes. A warning is a task, started in the turn that saw it or handed to the consolidation pass that turn starts, and only the user can defer one. Reading one and continuing is how a directory becomes unusable while every individual turn looks fine. Each warning names its fix. The ones that need more than that:
- The index is not imported. Add the import line the warning names to the instruction file it names, so the index loads at session start instead of depending on an agent choosing to open it. The structure reference has the lines to add.
- A link does not resolve. Point it at where its file is now, or unlink it as Filing says when the file is gone for good. In a project this session may not edit, report it to the user with its file and line.
- Context-Inbox is waiting. Drain it by the upkeep reference.
- A consolidation pass is due. Start it in this turn. Hand it to a fresh background subagent when the harness offers one, with the Context path, this skill, its upkeep reference, and the generator's other warnings, because the working session's context is full of its own task and the pass needs a clear view of the whole directory. Keep working, and leave the files the pass is editing and the warnings handed to it alone. When it reports, review it before it is committed: read the diff, not only the summary, and for each line the pass removed from an active document, confirm the fact is stale or find it in the tree. Restore what was lost. Without background subagents, run the pass before finishing the turn. Never record a pass that was not run.
Archive
Context/Archive/, or an Archive/ folder beside the documents it serves, preserves superseded, completed, or fully synthesized material that remains useful for provenance but is not current guidance. It is never in the active index. Archiving is not deletion and is not summarizing, so it is cheap and should not be agonized over. What it buys is an active surface small enough to read, which is the scarce thing. Retire aggressively from the active set and delete almost nothing.
Reconsider archival status when a phase closes, a decision is superseded, a one-time runbook is completed, a source is fully synthesized, or a newer owner absorbs the material. In a Git repository, when the only question is what a current document said before, history answers it, so update the document in place rather than archiving a copy of it. Read the upkeep reference before moving anything into Archive or rolling the old entries out of a log.
Validation
Before finishing a turn that changed Context or the state of the work:
- Check the handoff by reading the repository as a fresh agent would, with only the repository and the word "continue": it can find the current state, the intended next steps, the constraints, and the open questions without this conversation. Save what is missing, reconcile what the turn made stale, and record an unresolved question as unresolved.
- Confirm nothing is recorded as the user's decision that the user did not decide, and no line written in the turn says more than what supports it. Reread each line about what someone can, will, did, or did not do beside the words it rests on, and where those words are broader or silent, quote them, mark the line as the agent's reading, or remove it.
- When a source was filed, confirm every actionable line in it is captured with its quote, its time, and the owner and due time someone stated, written as absolute, or a note that nobody did.
- When the reply lists what is open, owed, or waiting, confirm each item passed the checks in Reading, and that an overdue item that still needs action is on it.
- Confirm current facts and opinions have one active owner, and that no document still states a value the turn replaced, the date, time, or place of an event included, outside dated records and archived text.
- Confirm rules for how an agent works live in
AGENTS.md, not in Context, and document-specific procedures remain with their subject.
- Confirm edited frontmatter matches the current purpose, and local links and active wiki links resolve. The generator checks inline Markdown links, in Context and into it from the folders it reads. Wiki links and reference-style links are checked by hand.
- Confirm directory density was reviewed rather than preserved by inertia.
- When Context changed, run the generator, fix frontmatter errors, and confirm every warning was acted on, handed to a running consolidation pass, or deferred by the user.
- In a Git repository, commit the turn's Context changes, and the
.gitignore line the generator may have added, in a commit of their own that stages only those paths, without asking the user, unless the project's instructions keep commits for them. Leave other work in the repository unstaged, and leave a running consolidation pass's files for its review. Push only where the project's instructions say to.
1---2name: "context-memory"3description: "Use for any work in a project where a Context directory exists, the user asks for one, or the project's instructions call for one, from investigation and routine edits to handoffs between sessions, even when nobody asks to save or remember anything. Captures and organizes the knowledge a project needs across turns and sessions, kept as what is true now: decisions, preferences, opinions, plans, next steps, current state, and discoveries. Also use to create, file, index, audit, tidy, or consolidate that Context, to drain a Context-Inbox directory or act on a due consolidation pass, and whenever a harness offers its own memory, recall, or auto-save store for that project's knowledge. Not for personal reminders or preferences that span unrelated projects. Code documentation, READMEs, and comments stay with the source, but work on them still triggers capture of project knowledge."4metadata:5 source: https://skillmd.com/skills/leeornahum/context-memory6 author: "Leeor Nahum"7 version: "4.5.0"8---910# Context Memory1112`Context/` is the project's memory: what it knows that is not code, as plans, research, decisions, rationale, status, schedules, references, and records. It is project knowledge, not a second instruction hierarchy.1314Topical documents state facts, opinions, constraints, decisions, and plans directly. Rules that govern how an agent works across tasks, including how the user wants to be worked with, belong in the nearest applicable `AGENTS.md`, where every session loads them. They do not go in a topical document, in the authored part of `Context/AGENTS.md`, or in a harness memory store. A plan, checklist, decision, or runbook may still contain instructions when those instructions are the subject of the document.1516## Where This Skill Applies1718This skill governs a project when a `Context/` directory in this format already exists there, when the user asks for one, or when the project's instructions call for one, whatever file carries them. Being installed is not one of those signals: availability in a catalog, a global skills folder, or a remote library does not make the skill apply, and a project with none of these signals keeps whatever it already uses.1920## Precedence Over Built-In Memory2122Where this skill applies, `Context/` is the durable store for project knowledge and it supersedes any memory feature the harness provides. Do not write project knowledge into those. When a harness memory store already holds some, migrate each fact into its owning Context document and leave the harness store empty.2324This governs durable project knowledge only. A preference that spans unrelated projects is not project knowledge, and this skill keeps no store for it. Write it as a rule in the `AGENTS.md` of each project where it applies.2526## Reading2728The index in `Context/AGENTS.md` lists every active document with when to read it. When it is already in your context, do not read the file again. Otherwise read it first. Open only the documents whose paths and descriptions match the task, and search within the relevant topic when more than one owner is plausible. Looking something up needs nothing else from this skill and no generator run.2930Building an agenda, schedule, reminder list, or any list of what is open, owed, or waiting for the user is more than a lookup, whether it comes from Context, a sweep of messages, or the session's own earlier replies. Build it fresh each time it is reported, never carried forward. Before an item goes on, check:3132- The messages, mail, and invitations the session can reach that are newer than the source the item rests on.33- Evidence that it was done, such as sent mail, receipts, shipment records, or files, of any date.34- The decisions made since, this turn's included.35- Whether it belongs to another project.3637A passed date or event starts the check and settles nothing either way: a plan whose date has passed is not done until something shows it happened. Leave off an item that is done, answered, made moot by a decision, never owed, or past with nothing left to do, and correct what Context still states about it. Do not mention what was left off, not even as a list of what is already done. An overdue item that still needs action stays on, and one the session cannot settle stays on worded as unconfirmed, never as done, missed, or unpaid. An item that belongs to another project goes to that project as Filing says. A disagreement between records about something past that changes no decision or next step is not raised and not recorded as unresolved, and dated records stay as written. Ask the user only when what the session can reach leaves an item undecided.3839## Capture4041Write project knowledge into its owning document in the same turn, unasked, whether it comes from the user, the work, or a source. Saying it once is the request, and nobody has to say save, note, or remember. Preserve what affects how the work continues or would otherwise need rediscovery:4243- Decisions, preferences, opinions, and constraints, with their reasons, and confirmed approaches recorded as readily as changed ones.44- Other people's commitments, availability, and progress, as readily as the user's own: what someone promised, when they are away or busy, what they are behind on.45- Asides and maybes about later work, however briefly said, recorded as open in the speaker's words.46- Rules for how to work with the user, written to the nearest applicable `AGENTS.md` in the turn they are given, even when that turn changes nothing else.47- Plans and next steps, with their timing and dependencies.48- Changes in the state of the work: what is done, what is waiting and on whom, what is due, and where anything made outside the repository lives.49- Discoveries from the work or a source, with a reference where it supports later verification.5051**State what is true now.** When the user or a source corrects or changes something, rewrite the owning statement so the document reads as if it had always been right, and remove the old value from every active document that states it as current. Reconcile what depended on the old value as this section's rule for a changed state, decision, or plan says, and where its new value is not known, mark it unconfirmed without citing the old value. Do not record the correction as an event, and do not keep the old value beside the new one. Keep an earlier value only when a later reader needs the history itself, such as the reason a plan moved, and leave dated records and archived text as they were written. In a Git repository, history holds what a document said before.5253A source that states a new value as now in force for something Context holds, such as the date, time, or place of an event, corrects it even when the user says nothing, so the old statement is edited, never joined by a second entry. An offer, a quote, or an option is not such a value until the user, or whoever sets the fact, accepts it. When the user sets the fact, their word corrects it and is not ranked. Between sources that disagree, the written word of whoever sets the fact outranks a relayed or spoken figure, and a later message outranks an earlier one from the same sender. Write the winner and remove the loser. When the outranked source is the newer one, or no ranking settles it, write neither as settled: record the fact as unresolved, name who can settle it if a source names them, and give any plan made in the meantime the event that ends it.5455Capture what the work established rather than narrating the turn. A log belongs in Context when its history is useful later in its own right, such as a record of runs, submissions, or contacts. When an event recurs, or the user says how to handle one, write the rule where the next run will read it, not only the log entry.5657**Never record a guess as the user's decision.** Keep proposals apart from agreed plans, attempts apart from finished work, and inferences apart from confirmed facts. Write a choice as decided only when the user decided it. A tentative remark is recorded as open, in the user's words. A line drawn from a source says only what the source says. A reading of what the user or a source meant is marked as the agent's reading, and an instruction relayed by another agent is attributed to that agent. Name who takes each pending step when the user or a source said who. A step the user said they will take is never left for the next session to take. Attribute to no one a step, follow-up, owner, or date they did not state, and mark a step the agent proposes as its proposal. Before reporting anything saved, match each line written in the turn to what supports it, the words of the user or a source or what the work itself showed, and mark as the agent's reading, or remove, any line that nothing supports. Call the user by a name only when the project's own files give one, never one taken from a skill, a tool, or the machine.5859Write a relative date (tomorrow, next week, in two weeks) as the absolute date counted from when it was said or sent, never from when it is filed. A line in a recording was said at the recording's start plus the line's offset, and the time a recording carries may be when it ended rather than when it started, so find which from the project's notes or the tool before counting from it, and when neither says, the time is unknown. Keep the precision given, such as the week of a date, and when the time of the source is unknown, keep the words and mark them unconfirmed. Something due, which someone committed to by a later date or event, is written with that date or event where a session will meet it before then: preferably a document the index says to read at every session start, otherwise the owning document, whose description names that date or event as the Frontmatter section says. A maybe or an idea keeps any timing its speaker gave but is not due.6061After a message or source that carries several items, go through all of it, not a summary of it. Filing it is not done until every actionable line in it is captured: what anyone promised, asked for, or advised that implies a step, with that step marked as the agent's reading unless it was said, every date set, what was said to an outsider that a teammate who was not there needs to hear, recorded as something that teammate needs to be told, and a reversal, which updates the earlier item to quote the later line instead of adding a second. Each item keeps its quote in the speaker's exact words and when it was said. It names the owner and due time someone stated, the due time written as an absolute date with a time of day when one was given, or it says that nobody stated them. Check each item against its owning document before reporting it saved. Tell who said or owns each line from what is said and from the project's files, not from labels alone, since speaker labels and display names drift. A turn that ends on a question or a hold still writes what the user decided or asked for in it. When the turn changed Context, run the generator, then end the reply with what was saved, in which document, and from which source, and say when each dated item comes up: its date, and the document a session will meet it in. In that report, an item found done, answered, or moot while checking gets no line of its own, and neither does a past disagreement settled while checking: say only which documents were brought up to date. A turn that adds or changes no such knowledge needs no capture update.6263**What the work shows in passing is a source too.** An email in a result list, a file in a folder, a message preview, or a page opened for something else is captured like any source when it bears on the project and Context does not already hold it, even when it is not the task. Open each item in such a list that might bear on the project, not only the one the task needed, and skip only what plainly does not. An attachment is content even when its message has no text: record who sent it, when, its file name, where it lives, and whether it is saved into the project. The capture report names what was saved besides the task.6465Update the owning document rather than adding a duplicate. When a state, decision, or plan changes, search the relevant documents for statements and procedures that depend on it and reconcile them in the same turn, keeping the current fact in one owner and linking to it elsewhere. When a dependent statement cannot stay true with the new value, mark that statement unresolved rather than writing it as settled. Delete what turns out to be wrong. When the user says to remove something, remove it. Record a standing rule against it only if it keeps returning.6667## Delegation6869The session that works with the user owns capture. A worker does not need this skill to do its task. When a worker's task depends on project knowledge, its brief names the Context documents to read, or tells it to start from the index. A worker returns what it learned in its report, and the session that briefed it files that in the same turn. A brief that hands a worker a long source, or a part of one, to read for its items tells it to flag every line that could be actionable, with its quote and time, and to over-flag rather than miss, and the briefing session decides which are items. When a brief does have a worker write to Context, the brief names this skill, and whoever holds the result runs the generator afterwards, so no index is left stale.7071## Filing7273- One current fact has one owner in Context. Other documents link to it, and a decision a README or another project file also shows is still stated in its Context owner.74- Organize by the project's real subjects. Before adding a file, decide which subfolder owns it, and create that subfolder in the same change when the subject has enough files to read as a group. Root-level files are reserved for project-wide owners such as current status or a master plan.75- A status document states the present and is edited in place. An item leaves it in the turn evidence arrives that it is done, answered, or moot. An item whose date or event has passed leaves once nothing is left to do. A durable fact gets an owner of its own before it leaves status, and dated history goes to a log.76- Use Title Case for folders and markup filenames. Name evergreen files for the subject they own, not the temporary task that created them. Prefix time-anchored records with `YYYY-MM-DD `, followed by the subject. A date alone is not a name.77- Aim for roughly 4 to 12 active markup files in a directory, and no more than 8 at the root. More than 12 triggers an organization review, and more than 20 means the directory needs clearer subtopics unless it is an intentional chronological or generated collection. Three or four levels of meaningful subdirectories are healthy. Folders are for filing: they give a new fact an obvious home and keep one subject's files together when a subject is renamed, split, or archived.78- File count and description length are the cost paid at every session start, because every active description sits in the index. Document length is paid only by a reader who needs it.79- Write Markdown. A file that is not a document sits in the folder of its subject, beside the document that uses it when there is one, and needs no document of its own. A document that mentions a file links to it.80- Every file in Context is there on purpose: a document, or a file kept for what it is, such as a video, an image, or the source that makes one, whether placed by hand or written there by a script. Context is never a working folder. Installs, caches, intermediate build and scratch output, and temporary downloads go outside Context, such as the session's scratchpad or temp folder. Whatever this task left in Context by accident is removed or moved out before the turn ends.81- Anything the user hands over to be saved, by whatever route, is filed in the form its content needs: text that arrived as a picture becomes text, pieces of one record that were split only by how they arrived become one document, and pieces that are separate on purpose stay separate.82- A fact can belong to another project. Search every project it could belong to before deciding where it goes or saying it was never saved. File it in that project's Context, or in its `Context-Inbox/` when this session may not edit it. Keep it out of this project's Context and out of what this session reports as open here.83- Before moving, renaming, or archiving a document, or filing one out of `Context-Inbox/`, the folder beside `Context/` where others drop material to be filed, search for its path and its filename across the whole project, not only Context, and in every other project that links into this Context, such as a sibling repository or a parent workspace. In the same change, in active documents, retarget every link, say that an archived target is archived, and correct every statement of where the document is or that it still waits in the inbox. In dated records and archived text, retarget the link only. The move changes no other line in those files, so their diff shows only those edits. A link whose target is gone for good becomes plain text or a code span.84- The authored part of `Context/AGENTS.md`, above the generated block, holds this directory's filing conventions only: where a kind of document goes, how it is named, how a recurring source from the inbox is filed. Write one when a convention would otherwise be reinvented, keep it to a few lines, change it when the directory changes, and follow it when filing.8586Read the [structure reference](references/structure.md) before creating a Context directory, adding a second one inside a project, moving or closing a project, splitting or merging a document, writing an HTML document, or filing a document that arrives with frontmatter of its own.8788## Frontmatter8990Every active Markdown file begins with:9192```yaml93---94name: <Title Case Document Name>95description: <one line saying what the file holds and when it is useful>96date_created: YYYY-MM-DD97date_modified: YYYY-MM-DD98---99```100101Descriptions are selection metadata. They name what the file holds and when it is useful, on one line, aiming under 200 characters and never over 1024, and they do not summarize the findings. A file that holds something due, other than a document the index says to read at every session start, leads its description with it, in the shape `Read by YYYY-MM-DD:`, or `Read by <event>:` when no date is known, inside the same limit, and drops it once nothing is left to do. The body owns the actual information.102103`name` matches the document, `date_created` is the day the document entered Context and never changes, and `date_modified` changes when the body's content changes, so it says when the document's knowledge last changed. A move, a rename, a retargeted link, a note that the document was superseded or archived, or an edit to the description alone is not a content change. The date an event happened belongs in the filename prefix and the body, not in these two fields.104105When a document records a time of day, write it in RFC 3339 with its UTC offset, in the shape `YYYY-MM-DDThh:mm:ss+hh:mm`.106107## The Generator108109Run the generator once at the end of a turn that changed active Context. It is one zero-dependency Node script, and both routes below run the same file:110111```bash112# Skill not on disk (served from a remote library)113npx --yes github:LeeorNahum/context-memory-skill <path-to-Context>114115# Skill on disk (a repository .agents/skills install or a global skills folder)116node <skill-root>/scripts/index.mjs <path-to-Context>117```118119Both routes need Node. The remote route also needs npm, Git, and network access.120121The generated block lists each active markup file as one bullet: its path, an arrow, and its description. It omits archived material and assets, validates active frontmatter, and preserves authored text outside the guards.122123The generator also checks links. It reads every inline Markdown link with a relative target under Context, Archive included. In the other Markdown files of the folder that holds Context it reads only the links that point into this Context or its inbox, because those are the ones a move, an archive, or a drain breaks. `--links=<folder>` adds any other folder that links in, such as the rest of the project when Context sits in a subfolder, a sibling repository, or a parent workspace, and is remembered for that Context. `--check` reports without writing anything, for a Context this session is reviewing and not editing, and what it reports goes to the session that owns that Context. `--help` lists the other flags.124125A whole-directory cleanup means an editorial audit, not only index regeneration. When the user asks for an audit, a tidy, a consolidation, or an inbox drain, follow the [upkeep reference](references/upkeep.md).126127## Generator Warnings128129**The generator's warnings are work, not notes.** A warning is a task, started in the turn that saw it or handed to the consolidation pass that turn starts, and only the user can defer one. Reading one and continuing is how a directory becomes unusable while every individual turn looks fine. Each warning names its fix. The ones that need more than that:130131- **The index is not imported.** Add the import line the warning names to the instruction file it names, so the index loads at session start instead of depending on an agent choosing to open it. The [structure reference](references/structure.md) has the lines to add.132- **A link does not resolve.** Point it at where its file is now, or unlink it as Filing says when the file is gone for good. In a project this session may not edit, report it to the user with its file and line.133- **Context-Inbox is waiting.** Drain it by the [upkeep reference](references/upkeep.md).134- **A consolidation pass is due.** Start it in this turn. Hand it to a fresh background subagent when the harness offers one, with the Context path, this skill, its [upkeep reference](references/upkeep.md), and the generator's other warnings, because the working session's context is full of its own task and the pass needs a clear view of the whole directory. Keep working, and leave the files the pass is editing and the warnings handed to it alone. When it reports, review it before it is committed: read the diff, not only the summary, and for each line the pass removed from an active document, confirm the fact is stale or find it in the tree. Restore what was lost. Without background subagents, run the pass before finishing the turn. Never record a pass that was not run.135136## Archive137138`Context/Archive/`, or an `Archive/` folder beside the documents it serves, preserves superseded, completed, or fully synthesized material that remains useful for provenance but is not current guidance. It is never in the active index. Archiving is not deletion and is not summarizing, so it is cheap and should not be agonized over. What it buys is an active surface small enough to read, which is the scarce thing. Retire aggressively from the active set and delete almost nothing.139140Reconsider archival status when a phase closes, a decision is superseded, a one-time runbook is completed, a source is fully synthesized, or a newer owner absorbs the material. In a Git repository, when the only question is what a current document said before, history answers it, so update the document in place rather than archiving a copy of it. Read the [upkeep reference](references/upkeep.md) before moving anything into Archive or rolling the old entries out of a log.141142## Validation143144Before finishing a turn that changed Context or the state of the work:145146- Check the handoff by reading the repository as a fresh agent would, with only the repository and the word "continue": it can find the current state, the intended next steps, the constraints, and the open questions without this conversation. Save what is missing, reconcile what the turn made stale, and record an unresolved question as unresolved.147- Confirm nothing is recorded as the user's decision that the user did not decide, and no line written in the turn says more than what supports it. Reread each line about what someone can, will, did, or did not do beside the words it rests on, and where those words are broader or silent, quote them, mark the line as the agent's reading, or remove it.148- When a source was filed, confirm every actionable line in it is captured with its quote, its time, and the owner and due time someone stated, written as absolute, or a note that nobody did.149- When the reply lists what is open, owed, or waiting, confirm each item passed the checks in Reading, and that an overdue item that still needs action is on it.150- Confirm current facts and opinions have one active owner, and that no document still states a value the turn replaced, the date, time, or place of an event included, outside dated records and archived text.151- Confirm rules for how an agent works live in `AGENTS.md`, not in Context, and document-specific procedures remain with their subject.152- Confirm edited frontmatter matches the current purpose, and local links and active wiki links resolve. The generator checks inline Markdown links, in Context and into it from the folders it reads. Wiki links and reference-style links are checked by hand.153- Confirm directory density was reviewed rather than preserved by inertia.154- When Context changed, run the generator, fix frontmatter errors, and confirm every warning was acted on, handed to a running consolidation pass, or deferred by the user.155- In a Git repository, commit the turn's Context changes, and the `.gitignore` line the generator may have added, in a commit of their own that stages only those paths, without asking the user, unless the project's instructions keep commits for them. Leave other work in the repository unstaged, and leave a running consolidation pass's files for its review. Push only where the project's instructions say to.