Save knowledge that will affect subsequent work as a project asset that is inspectable, migratable, and has a controllable lifecycle. The default data directory is under the project root .memory-3layer/；MEMORY_DIR can be explicitly overridden.
Goal contract
For users who are working on long-term projects and switch Agents across sessions, generate a set of three-layer memory that both humans and Agents can inspect, and satisfy the following observable criteria:
- Layer 1 is in
areas/topics/<topic>/items.jsonsave structured facts with status. - Layer 2 is in
memory/YYYY-MM-DD.mdsave a work trail appended by date. - Layer 3 is in
MEMORY.mdsave human-confirmed long-term tacit knowledge. - New sessions load only budget-constrained active content, and do not stuff the entire history into the context.
- Old knowledge can be marked as
superseded, without relying on deleting history to create the "latest facts". - The automation for Claude Code and Codex both call the same Python core; other platforms are not disguised as automatically supported.
Triggers and non-triggers
Use this skill:
- The user asks to "remember this rule", "continue next time", "save across sessions", or "view/clean up project memory".
- The project already has
.memory-3layer/, and the current task needs to read the long-term context in it. - The project still has
.claude/memory/, and the user wants to migrate to a platform-neutral directory. - Need to wire up the three-layer memory lifecycle for Claude Code or Codex.
Do not use:
- Only need to write a one-off log, cache, build output, or full session dump.
- The content contains passwords, tokens, private keys, payment information, unmasked personal data, or material that should not enter the version repository.
- The user only wants to use the host's own private memory, and does not need project-level sharing and lifecycle management.
First action
Before writing, first confirm five facts: the project root directory, the current host, whether.memory-3layer/ exists, whether legacy .claude/memory/ exists, and whether the current task authorizes writing. When the project root directory or write permission cannot be confirmed, only report the findings, and do not create or migrate files.
Inputs and outputs
Inputs:
- Project root directory; by default the current Git root, and for non-Git projects use the current working directory.
- Current runtime platform:
claude、codexormanual。 - Content the user explicitly asks to remember, or the event payload provided by the host Hook.
- Optional environment variables:
MEMORY_DIR、MEMORY_MAX_ITEMS、MEMORY_DAILY_DAYS、MEMORY_TOPICS。
Outputs:
.memory-3layer/The changed three-layer memory files in .- Summary of this action: what was read, what was written, what was skipped, and what the next step is.
- On failure, give the specific failure path, and do not describe "Hook configured" as "Hook has run".
Execution step contract
| Step | Input | Action | Observable output | Transition condition | Failure path |
|---|---|---|---|---|---|
| 1. Locate | cwd, Git status, host identifier | Determine project root, runtime platform, data directory, and write permissions | Output four location results | Path is unique and permissions match the task | If the path is not unique, ask; if there is no write permission, switch to a read-only status check |
| 2. Initialize or migrate | Current directory, legacy directory, user authorization | New project initialization .memory-3layer/; legacy is copied and verified only during explicit migration, and is not overwritten by default |
Standard directories exist; migration report lists copied/skipped/conflict | Structure verification passes | Stop on conflict or when the target is non-empty, do not delete the source directory, and hand off for manual handling |
| 3. Load | active facts, recent journal,MEMORY.md, budget parameters |
Assemble a constrained context in the order Layer 3 → Layer 2 → Layer 1 | The loader returns readable context and entry counts | Output stays within budget and sources are traceable | When a file is corrupted, skip the bad file and report it; do not silently rewrite |
| 4. Record | Explicit user memory, confirmed memory protocol, existing entries | Call scripts/record_memory.py, and after desensitization, classification, and deduplication, append to Layer 1/2; only promote manually confirmed long-term conclusions to Layer 3 |
The file diff shows additions or deduplication skips | Each record has a source, date, and status | Ordinary tool output is not automatically persisted; when content contains secrets, has an unknown source, or is merely speculation, refuse and explain the reason |
| 5. Session protection | PreCompact/equivalent event or manual request | Save the minimum recoverable state, do not save the full chat log | The session state is parseable and contains time and summary | Write completes atomically | Hosts without a corresponding event degrade to manual save and do not claim automatic recovery |
| 6. Review | Three-layer files, dates, status | Identify duplicate, conflicting, and outdated entries, and propose active → superseded suggestions | Review report and item-by-item suggestions | Change status only after user confirmation | When it is impossible to determine which is newer, keep the original state and mark it as pending confirmation |
| 7. Verify | Package files, temporary project, host configuration | Run package verification and target platform tests; check whether Hooks actually trigger | Report results separately for the artifact, adapter, and runtime layers | All required layers have evidence | When only static verification passes, it may only be called "configuration complete," not "automatic operation verified" |
Platform capability matrix
| Platform | Agent Skills | Automatic lifecycle | Wiring location | Prerequisites for use |
|---|---|---|---|---|
| Claude Code | Yes | Yes, adapted to SessionStart、PostToolUse、PreCompact |
.claude/settings.json |
Python is available; project Hooks are enabled |
| Codex | Yes | Yes, adapted to similar Codex Hooks events | .codex/hooks.json |
Python is available; after installation, in /hooks review and trust the project Hooks |
| Other hosts that support Agent Skills | Depends on the host | No | No auto-wiring | Use manual core, explicitly load, record, and re-check |
"Supports Agent Skills" does not equal "automatically supports its Hook protocol." Without an adapter or runtime evidence, always mark it as manual.
Six boundary types
- Non-goal boundary: does not replace Git, databases, backups, or host-native memory, and does not store full chat history.
- Source-of-truth boundary: only record user-confirmed facts, file evidence, or known Hook fields; model inferences must be marked and cannot be directly promoted to long-term facts.
- Permission boundary: read public memory within the project; writing, migration, and state modification must comply with user authorization, and do not modify global configuration outside the project.
- Side-effect boundary: by default only modify
.memory-3layer/and explicitly selected platform configuration; merge existing configuration, do not overwrite unrelated Hooks; do not automatically commit to Git. - Stop boundary: when there are secrets, path ambiguity, format corruption, migration conflicts, configuration that cannot be safely merged, or validation failures, immediately stop the corresponding write operation.
- Fallback boundary: when automatic Hooks are unavailable or untrusted, fall back to manual; retain core read/write capability, but clearly state that automatic loading/extraction/compression protection did not occur.
Migration rules
The old default path .claude/memory/ is only used as a read-only discovery source, and is no longer the default value for new writes. Run it only when the user explicitly requests migration:
python scripts/migrate_legacy_memory.py --project-dir <目标项目>
Migration copies to .memory-3layer/by default, does not overwrite existing files, and does not delete legacy. For complete conflict rules, see references/migration.md。
Explicit recording
When the user says "remember," the Agent calls the controlled recording entry point; do not assume that ordinary PostToolUse output will automatically become fact:
python scripts/record_memory.py --project-dir <目标项目> --fact "这个项目统一使用 pnpm" --topic workflow
Only top-level memory_fact passed in by this package's managed recorder can be persisted. Any summary、fact、confirmed in tool responses or other raw output is ignored by default.
Progressive loading
- Need to install, trust, or troubleshoot host wiring: read references/runtime-adapters.md。
- Need to judge input/output, source of truth, and failure routes field by field: read references/operating-contract.md。
- Discover
.claude/memory/or the user requests changing paths: read references/migration.md。 - Need to understand the three-layer directory and data flow: read docs/architecture.md。
- Need to give the user the shortest onboarding steps: read docs/quickstart.md。
Verification
First verify the platform-neutral core, then verify the target platform adapter:
python scripts/check_memory_3layer.py
python -m unittest discover -s evals -p "test_*.py"
Static tests cannot prove that the host has triggered the Hook. Claude Code requires observing load events in a new session; Codex requires first passing /hooks trust, then observing load events in a new session. When reporting, write separately:
artifact_status: whether files and structure are consistent.adapter_status: whether platform configuration was merged successfully.runtime_status: whether real host events were triggered and produced the expected output.
Release source
The current public source is KimYx0207/Kim_Service in skills/memory-3layer/. The old KimYx0207/claude-memory-3layer only retains historical provenance and is no longer used as an installation source or basis for current capability claims.