Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Knowledge and memory

Status
Review
Version
0.2.0
Authority
UASK standard
Applies to
Core
Markdown source

Summary

An agent starts every session with an empty context, so a project needs a stated place for what it knows and a stated moment to read and write it. This item names four memory layers and gives each its authority: only files in Git are the source of truth; a search over files, notes of outcomes and an agent’s own memory files only point to them or hold evidence until it is promoted. It says what is recalled at the start and recorded at the end of each phase, how a lesson travels from a note to a knowledge-base entry, a Hub item and finally a check, how recall is kept from copying another client’s personal data, and how a memory tool is judged before it is adopted.

Rules

The layers

  • R1. A project MUST treat its memory as four layers and MUST keep anything normative in the first only:
    1. Files in Git: decisions, the Blueprint, release specs, the knowledge base (the project’s own collection of lessons and pitfalls), each site’s shared notes. This layer is the source of truth.
    2. Search over files: finds existing text across the project’s folders. It is a pointer into layer 1.
    3. Outcome memory: what was tried and what happened, recorded during work that no file holds yet. It is evidence until it is promoted (R10).
    4. Session memory: the owner’s preferences and feedback for agents, kept by the agent’s tool. It is an instruction to the agent, never a project fact.
  • R2. A decision, rule or fact that the project depends on MUST have one home in layer 1 (process.project-lifecycle#R14). When recall finds it in layers 2 to 4, it MUST be written to its home before it is relied on.
  • R3. The project MUST name the search tool it uses once, in the file where it keeps its rules for agents, as “the one in use”. This item does not prescribe a tool. A search hit is a pointer: the agent MUST open the file it points to and cite that file, and MUST NOT copy the excerpt as a fact.
  • R4. Outcome notes (layer 3) MUST be kept where the project keeps its log, with the date, the phase, what was tried and what happened. A log is a file, but its outcome lines belong to layer 3 by authority: evidence until they are promoted (R10). A project MAY adopt a tool for this layer only after R13.
  • R5. Layer 4 MUST NOT hold a project fact or decision, or personal data of a client or another person. A fact or decision found there MUST be moved to layer 1 and removed from the memory file. An owner’s instruction to agents (“never ask this”, “report in five lines”) MAY stay in layer 4, because it is the owner’s own channel; when it governs the project, the agent proposes it for the project’s rules file (R12) and keeps the memory entry until the owner’s file holds it.

Recall and record

  • R6. Each phase MUST open with a recall step and close with a record step (process.project-lifecycle#R13), with the contents of the table “Recall and record in each phase” of that item. The log MUST show that recall was done: one line with the question, the tool, and what was used. “Nothing relevant found” is a valid line.
  • R7. Recall informs a decision and never makes it (process.project-lifecycle#R14). A recalled outcome MUST be checked against the file it points to and its date before it changes an estimate, a decision or a check.
  • R8. A record MUST say where it lives and what kind it is: a file (decision, spec, release record, postmortem) or an outcome note (R4). A phase MUST NOT close with a decision that exists only in an outcome note or in a session.

Personal data in recall

  • R9. A recall hit MUST be treated as possibly holding personal data of another client or person. What the agent writes into a brief, spec, estimate, log or Hub item MUST give a past case as a name of the project and figures, and MUST NOT copy another client’s name, telephone number, email address, postal address or order data. The recall line of R6 MUST say whether a hit held personal data (“personal data in a hit: yes or no”), so the frequency can be counted; the data itself MUST NOT be copied into that line. The client-brief step already keeps this count in its run record (mgmt.project-foundation); this rule extends the same field to every phase. A client brief and anything derived from a client’s request stays in the project’s private folder (mgmt.project-foundation#R19).

The route of a lesson

  • R10. A lesson MUST be promoted in this order, and each step MUST record its target: outcome note → knowledge-base entry (with its source: project and date) → Hub item (only if it is general, and with every client, name and figure removed) → a check that fails when the lesson is ignored. An outcome that occurs a second time MUST be promoted.
  • R11. There is one route for every kind of lesson: a postmortem (ops.incidents-and-postmortems#R12 and #R13), a risk that occurred (arch.risks-and-technical-debt#R7), a review finding, and a “to playbook” line in a log. Each ends in a new check, a decision or rule in layer 1, or a knowledge-base entry, and the record says which. A lesson MUST NOT end as “noted”.
  • R12. A lesson that proposes a change to the Hub MUST be sent as a proposal with the evidence (what happened, in which phase, what check would have caught it). The owner or the lead decides (mgmt.roles-and-decision-rights); memory MUST NOT change a Hub rule by itself.

Judging a memory tool

  • R13. A project MUST NOT adopt a tool for layer 3 on the vendor’s claim. It MUST measure it by round trip: write a set of facts, ask for each in other words from a fresh session, and compare the answers with a control that has only files and search (layers 1 and 2). The result, including a negative one, MUST be recorded. A tool that does not beat the control SHOULD NOT be adopted.

By tier

  • R14. The tier (mgmt.governance-tiers) changes how much is written, not what recall may do. R2, R3, R5, R7, R9 and R12 hold at every tier, and so does R13 whenever a layer-3 tool is adopted. At the lightweight tier a project MAY skip the recall line of R6 and MAY stop a lesson at the knowledge-base step of R10. At the high-assurance tier the owner MUST also see the promotions made in a release (R10) in its release record.

Guidance

The four layers in a small project

A typical project already has them. Layer 1 is the repository: decisions, the Blueprint, the release specs, the site’s shared notes and a folder of lessons. Layer 2 is a semantic search over those folders, or plain grep when the project is small. Layer 3 is the section of the log headed “to playbook” or “lessons”. Layer 4 is the memory the agent’s tool keeps for the owner’s preferences (“never ask this”, “report in five lines”). The common failure is to let layer 4 grow into a second source of truth: a fact stored there is invisible to the next person and to a different agent.

Recall in one line

Recall is cheap if it is a habit and expensive if it is a task. At the start of a phase ask one question of the search (“have we built a shop on this platform before, and what went wrong?”), open the two or three files it points to, and write one line in the log: the question, the tool, what you used. If a hit shows a client’s name and telephone number, do not copy the paragraph: write “a shop on the same platform, 5 days, payment module failed at the first test”, and mark “personal data in a hit: yes”.

The route of a lesson

Where it appears Where it goes first Where it ends
A failed attempt in Build outcome note in the log knowledge-base entry; a check if it can be tested
An escaped defect postmortem a new check (ops.incidents-and-postmortems)
A risk that occurred the risk register entry, closed as “occurred” a check, an ADR or a new input of the list (arch.risks-and-technical-debt)
A review finding that repeats the review report a Hub item or a rule of the project
A pitfall of a platform outcome note, then knowledge-base entry a Hub item if it holds beyond this project

Judging a tool

A round trip is the only test that matters: a store that accepts facts is not a memory until the right fact comes back to a question put in different words. Keep a control. If files and search alone answer the question, the tool adds cost and a second source of truth for nothing. Report negative results: they are the most useful part of the evidence.

Common mistakes

  • Treating a search hit as a fact without opening the file.
  • Keeping a project fact or decision in the agent’s own memory file.
  • A lesson that ends as a note nobody reads.
  • Copying a past client’s contact details into a new estimate because they were in the hit.
  • Adopting a memory tool because it demonstrates well, with no control.

Explanation

Why only files are normative. Memory held by a tool depends on the tool: it can be lost, it can be wrong, and a different agent cannot read it. A file in Git has a history, an owner and a review. Instruction files and automatic notes are loaded as context, and the documentation of the tool says they are not enforced configuration, so a rule that matters has to live where a check or a person can enforce it. Why a pointer, not a copy. An agent that loads references and reads the files when it needs them keeps its context small and works from the current text; a pasted excerpt ages. Why record where a lesson went. A lesson with no target is a note; the record of the target is what lets a reviewer see that the loop closed. Why a round trip with a control. A memory tool is a claim about retrieval, and a claim about retrieval is tested by asking. In a trial of a memory store run for the Hub (reports CC-048 to CC-051, July to August 2026, a private repository), the round trip over a fixed set of 20 facts recovered 0 of 20 at first, then 5 of 20 and 7 of 20 (13 of 20 when more cases were returned), while a control that had only the files scored 18 of 20; the ceiling was set by retrieval returning one subject per question, not by storage. With 20 facts the interval is wide and no production-embedder figure exists, so the lesson kept is the method, not the product. Why personal data is a rule here. Recall crosses project boundaries by design, so a hit about one client can surface in the work for another; UK data protection asks for data that is adequate, relevant and limited to what is necessary, and a copied contact detail is none of those.

Examples

Good. At the start of Spec for a small shop, the lead asks the search for earlier shops on the same platform and opens two files. The log line reads: “Recall, 21 Nov: earlier shops on this platform; search; used the case file of the 2026 shop (5 days) and the pitfall note on payment modules; personal data in a hit: yes (not copied).” At Release a rollback note goes into the knowledge base with its source. A month later the same failure occurs; because it occurred twice it is promoted to a check, and the record names it.

Bad. The agent stores “the client prefers phone calls, number …” in its own memory file, pastes another client’s reply from a search hit into the estimate, and ends a postmortem with “lesson learned: be careful”. Nothing is in Git, the estimate carries a stranger’s contact details, and the lesson has no target.

Sources

  • Claude Code documentation, How Claude remembers your project — Anthropic; all rights reserved; summarised, not copied: the two kinds of persistent context and that they are context, not enforced configuration. Accessed 2026-11-21.
  • Anthropic, Effective context engineering for AI agents — Anthropic; all rights reserved; summarised, not copied: notes kept outside the context window, and references loaded just in time. Accessed 2026-11-21.
  • ICO, Data minimisation — Information Commissioner’s Office; Open Government Licence v3.0; personal data adequate, relevant and limited. Accessed 2026-11-21.
  • The round-trip reports of the memory-store trial (CC-048 to CC-051, 2026-07-31 to 2026-08-09, a private repository; summarised, no data copied) and the dry run of the client-brief step, whose finding G3 is rule R9.