The operational procedure is carried by the
s4u-memory-disciplineskill. This appendix explains the model and its limits.
Appendix D: Memory System
Memory preserves useful context across sessions. It does not become the authoritative source of business intent, grant permission, or prove what is running in production. A good memory store helps a reader find the right evidence without having to rediscover why a choice was made.
In one line: retain the minimum authorized context, point to maintained records, and verify before acting.
1. Hub-and-Spoke Architecture
The Problem
Conversation history, working notes, accepted decisions and deployed state are different things. Flattening them into one increasingly long “memory” file loses both provenance and context. Private exploration can also leak when a useful summary is automatically copied into shared documentation.
The Structure
Use an explicitly selected storage location, not a guessed runtime path:
<authorized-memory-directory>/
MEMORY.md # small topic index
index_all_topics.md # optional generated catalogue
deployment-evidence.md
feedback-schema-tests.md
The hub orients a new session. Spokes supply detail on demand. The actual host determines which files are automatically loaded, how much is loaded and how retrieval works. An index is not a retrieval implementation or an access-control boundary.
This is a proposed operating pattern, not functionality supplied by the memory scripts. In the future workspace, permissioned retrieval and exact-revision approvals belong to the control plane described in Governed Factory.
Why Hub-and-Spoke
Keeping detail out of the hub reduces recurring context cost. A topic index is easier to maintain than a chronological session diary. Neither a short hub nor a good description guarantees that an agent read, understood or obeyed it.
The kit applies a 24,000-byte local hygiene budget, not a universal vendor limit. Check the selected host's additional limits separately. Claude Code documents its own startup loading limits and memory inspection tools; do not extrapolate those to other agents or future versions. Host memory documentation.
MEMORY.md Format
The copyable source is templates/memory/MEMORY-template.md. Keep durable orientation before perishable work:
# Project Name
## Mission & Quality Standards
A concise, approved description.
## Architecture Quick Reference
- Approved architecture and current profile: <authoritative reference>
## User Preferences
- Confirmed, scoped communication preference: <source>
## Known Technical Debt
- Active constraint: <maintained issue, owner and last review>
## Detailed References
- Topic catalogue: index_all_topics.md
## Upcoming Tasks
- Current next action: <maintained plan, owner and last review>
Do not create links to files that do not exist. A memory directory can be private even when the source repository is public; review its audience separately.
Anti-pattern: the journal-shaped hub
Appending every finished task grows the hub without improving orientation. Replace current summaries in place and move only non-obvious lessons into spokes. Completion history belongs in the maintained work system or release record.
Earlier examples in this appendix described observations from particular projects. They are not a benchmark establishing that a hub shape causes a particular retrieval success rate. Measure your own navigation and retrieval failures.
A generated topic catalogue can help find unreferenced spokes. The supplied templates/scripts/gen-memory-index.sh is a local navigation helper; inspect its supported input format and output before adopting it. Its catalogue does not establish authorization, guaranteed discovery or successful context loading.
The generator accepts [--check] [memory-dir-or-file], with S4U_MEMORY_PATH as a fallback. It reads immediate regular, unlinked Markdown spokes with closed, single-line frontmatter: conservative plain strings, JSON-style double-quoted strings or YAML single-quoted strings. Quote numeric-looking values. Duplicate keys/topics, complex YAML, unsupported separators and files above 4 MiB are unassessed. Simple safe topic IDs/filenames are required; this is not a general YAML parser.
Generation replaces only a catalogue carrying this profile's exact generated header/marker. Older or authored catalogues are deliberately left untouched: review and preserve any human content, then explicitly migrate the exact target before regeneration. Do not relabel an unread file as generated to bypass this safeguard.
Writes use an exclusively created local lock and same-directory staged replacement, with an ordinary concurrent-edit check. A stale lock is an investigation item, not permission to delete another process's lock. This does not establish hostile-filesystem safety or power-loss durability. --check is read-only: 0 means the compared supported inputs match, 1 means stale/absent, 2 means unassessed. Diagnostics do not print private metadata or diffs.
Known divergence: the 250-character bullet rule
The current rule is consistent across the skill and advisory hook: a hub bullet's content after its marker is at most 250 Unicode code points and occupies one physical line. Details go into spokes, not indented continuation lines. UTF-8 bytes and code points are different measures: the whole-file limit is 24,000 bytes.
templates/hooks/memory-budget-check.sh checks the configured file, common Markdown bullet markers and indented continuations. It reports line numbers and counts, never the contents of an entry. Unreadable configured input is explicitly unassessed. An unset path disables this optional check.
It is advisory and returns zero. Plain output from a successful Stop hook may only be available in debug output, so a working team must decide how warnings are observed and resolved. It is not a blocking gate or a loading receipt. Hook output behavior.
File Naming Conventions
Use descriptive lowercase hyphenated filenames, such as feedback-schema-tests.md. Preserve established filenames when renaming would break references. A source observation date belongs in the record; public publication metadata is a separate concern.
2. Four Memory Types
The four types are a curation convention. Frontmatter name, description and type make records legible; they do not create a universal relevance-matching service.
2.1 Type: user
Record confirmed preferences needed for collaboration, scoped to the project and audience. Do not infer a personality profile or collect unnecessary personal information.
A preference for autonomous routine work means fewer redundant questions within current authorization. It does not authorize a production migration, external upload, spend, publication, cross-customer sharing or destructive cleanup.
2.2 Type: feedback
Capture a lesson with Why and How to apply, its source, applicability and review status. A past correction can itself be wrong. Publish a dated correction to active guidance while preserving the original evidence under the applicable retention policy.
For example, a mocked test that missed database semantics justifies a real database test for that claim. It does not prove that all unit-level mocks are invalid or authorize calls to paid services. See Testing Standard.
2.3 Type: project
Retain non-obvious context and pointers to maintained plans, decisions or blockers. Distinguish a proposal from an accepted decision and identify the exact revision accepted by the authorized owner.
Resolve relative dates against the source's date and time zone. If “next Friday” is ambiguous, record that ambiguity instead of manufacturing a deadline.
A still-valid blocker remains relevant however long it has existed. A merged implementation does not resolve a deployment, activation or business-acceptance dependency by itself.
2.4 Type: reference
Point to approved runbooks, authoritative terminology, research and accepted architecture. Link rather than duplicate volatile dashboard URLs, command syntax, alert thresholds or dependency versions.
Research storage also needs an audience and retention decision. “Persist research” does not mean “publish research.” Store evidence and concise decision rationale, not private model chain-of-thought.
3. What NOT to Save
Do Not Save
| Material | Better home or treatment |
|---|---|
| Credentials and unnecessary personal data | Do not place in memory; use authorized secret/data handling |
| Raw private exploratory transcripts | Retain only in authorized source storage, under its retention policy |
| Accepted business rules or ADRs | Versioned authoritative artifact; memory holds a pointer |
| Current code structure, dependency versions | Inspect the relevant revision and lockfiles |
| Deployment and migration claims | Environment-specific release and runtime evidence |
| Entire task history | Maintained plan, issue or release records |
| Private model reasoning | Store concise rationale and supporting evidence instead |
The Derivability Test
Can the fact be obtained reliably from its maintained source? Prefer a pointer. Code explains observed implementation; it does not necessarily explain intended business behavior. A mined rule is an observation until validated.
The Duplication Test
Is the same fact already maintained elsewhere? Update the authoritative location through its proper workflow. Memory must not quietly become a competing requirements master.
Before both tests, apply the privacy test: are persistence, this destination and these readers authorized?
4. Staleness Management
The Staleness Problem
A record can be old but still valid, or newly written but wrong. Review dates help triage; they are not evidence of correctness.
Rules
- Name the subject and revision of a recalled claim.
- Check the appropriate source: accepted artifact, code revision, deployed environment or actual observation.
- Separate observed facts, inferences, proposals and approvals.
- Correct active guidance with provenance and a reason. Do not silently edit accepted history.
- Remove resolved orientation from the hub without deleting its authoritative record or required evidence.
- Keep unresolved blockers current through links, ownership and review—not by resetting their age.
Staleness Indicators
Do not assume every host adds age reminders. Configure and test any reminder mechanism you adopt. A last_verified field means only what the named verification actually checked; changing its date cannot refresh the underlying evidence.
Memory vs. Tasks vs. Plans
| Mechanism | Role | Lifetime |
|---|---|---|
| Memory | Orientation and curated lessons | Until corrected, superseded or removed under policy |
| Maintained work item | Work, owner, dependencies and resolution | Through closure and required retention |
| Accepted design/ADR | Approved intent or decision | Until authorized replacement or retirement; history retained |
| Generated STATE.md | Timestamped machine observations | Snapshot only; regenerate before relying on freshness |
Feature shipment does not retire an accepted design. See Project State Files and ADRs.
5. Cross-Project Memory Patterns
Directory Structure
Resolve the host's configured private/project memory locations during onboarding. Do not create a guessed .claude/projects/... directory inside a repository or assume it is ignored by Git.
Memory Composition
Record which organizational policies, project instructions and selected memories actually apply. A file's existence is not evidence it was loaded. Inspect the host's supported context diagnostics where available.
Global vs. Project-Scoped
Customer-specific constraints stay customer-specific. Shared worktrees, global instructions and search indexes may expand an entry's audience. Check those boundaries before saving even a short summary.
When to Promote to Global
Promote only with cross-project applicability and permission for the expanded audience. Generalize the lesson without copying customer names, proprietary rules, private sources or credentials. Repetition across projects is a reason to propose a reusable rule, not permission to publish it.
6. Setting Up a Memory System
Initial Setup
Choose storage, readers, retention, host-loading checks and ownership. Start with a minimal hub of known, authorized facts. Do not pre-populate fictional lessons or copy example identities as real facts.
When Memories Emerge
A correction, useful lesson or unresolved ambiguity can warrant a memory. An exploratory idea remains a proposal; a BA-reviewed summary still requires the accountable business owner's approval when it changes business meaning.
Maintaining the Hub
Check authoritative links, current applicability and unresolved ownership. Refresh the optional catalogue, review the output without exposing private contents, and apply the local budget. Keep current work last and concise.
Memory File Template
---
name: descriptive-topic
description: Concise navigation description
type: reference
---
**Scope/audience:** Authorized project team.
**Source:** Exact maintained reference or observation.
**Observed/reviewed:** Absolute date, reviewer; unknown if not established.
**Status:** Observation / proposed guidance / current guidance / superseded.
**Why:** Problem prevented.
**How to apply:** Specific procedure and its authorization limits.
These fields document provenance; a future workspace must enforce permissions and exact-revision bindings in its runtime. Markdown alone does not.
7. Memory System Metrics
Use measures that expose failures: broken references, unreviewed volatile claims, retrieval tasks completed with the right source, obsolete guidance acted upon and unauthorized disclosure incidents. File counts and “one memory per day” are not quality targets.
Measure observed loading and retrieval separately from index completeness. A catalogue can be complete while the agent retrieves the wrong context.
8. Summary
Keep memory small, scoped and navigable. Treat its contents as claims to verify—not present-day authority. The authoritative source depends on the claim: approved intent, accepted architecture, code, runtime evidence or the original observation. No single file replaces all of them.