MIZ OKI Claude Memory v2 — Architecture and Operating Process

Status: Implemented in repository
Owner directive: August 5, 2026
Canonical index: CLAUDE_MEMORY.md
Runtime: scripts/claude_memory.py

Executive design

The former root CLAUDE.md mixed constitutional rules, current directives, release notes, deployment evidence, and years of session history. Claude Code loaded that file at startup, so historical volume competed with the current task.

Memory v2 keeps all information but changes how it is loaded:

CLAUDE.md                         fast bootstrap + bounded active inbox
CLAUDE_MEMORY.md                  compact shared index
.claude/rules/                    automatic/global and path-scoped rules
.claude/memory/active/            current domain memory
.claude/memory/inbox/             records extracted during rollover
.claude/memory/archive/           immutable full-fidelity history
.claude/memory/manifest.json      precedence, routing, limits, Drive policy
.claude/memory/index.json         generated hashes/headings/search metadata
scripts/claude_memory.py          CLI entrypoint
scripts/claude_memory_common.py   manifest, indexing, validation
scripts/claude_memory_routing.py  selective routing and hooks
scripts/claude_memory_ops.py      rollover, recorder, Drive sync

The key principle is index everything; load only what is authoritative and relevant.

Why v1 was replaced

The prior system used a 40 KB threshold, retained the first 2,000 lines, appended the rest to one claudememory.md, depended on a machine-local pre-commit hook, and hard-coded a single Mac path.

That model had five failure modes:

line position was treated as importance;
the archive became another monolith;
.git/hooks enforcement did not travel with the repository;
hard-coded paths failed across machines and users;
copying history did not create a routing or precedence model.

The legacy commands now call the v2 transaction engine.

Authority and conflict resolution

Memory does not create a new constitutional layer. The resolver applies:

CONSTITUTION.md
AGENTS.md, OPERATING_SYSTEM.md, GOVERNANCE.md, TRUTH.md
canonical platform skill and governed source-of-truth code
README.md
CLAUDE.md and CLAUDE_MEMORY.md
active and path-scoped memory
archives

An archive can show what happened. It cannot override current law, code, or verified live state.

Startup and prompt flow

Session start

The SessionStart hook performs structural validation and adds a concise reminder. It does not inject the archive.

Prompt submission

The UserPromptSubmit hook:

tokenizes the prompt;
adds modules marked always;
scores manifest keywords;
scores path hints;
performs bounded content search;
checks each archive's bounded search-term/heading catalog before reading archive bytes;
scans at most four candidate archives, only when the catalog or explicit historical intent matches;
returns a small required-read list with targeted line hints.

Core governing files are mandatory regardless of relevance score.

Instruction audit

The InstructionsLoaded hook writes a local JSONL receipt under .claude/.runtime/. Runtime audit files are intentionally not committed or synced.

Threshold policy

Layer	Warning	Hard	Response
`CLAUDE.md`	16 KiB or 150 lines	20 KiB or 180 lines	rollover before append
`CLAUDE_MEMORY.md`	18 KiB or 180 lines	24 KiB or 200 lines	split detail into modules
Active module	48 KiB or 400 lines	64 KiB or 500 lines	split by bounded domain
Archive segment	8 MiB preferred	12 MiB	begin another immutable segment

A byte or line threshold is sufficient to trigger the action.

Initial migration

The complete pre-migration file is preserved at:

.claude/memory/archive/2026-08-05-CLAUDE-v6.45.48-7ef45e024654.md

Expected Git blob:

7ef45e024654c712dbcc30fffdb7e5ea7225d98c

Source commit: 68cbb42dd94d2fc123bae68e9e8c67dd2dbf04f5
Source size: 788,903 bytes

The archive entry is created using the existing Git blob SHA, so no transformation is introduced. Strict validation recalculates the Git blob identity from local bytes.

The active marketing/commerce connector directive was promoted into:

.claude/memory/active/marketing-commerce-connectors.md
.claude/rules/marketing-commerce-connectors.md

Recording a durable lesson

Use:

python3 scripts/claude_memory.py record \
  --title "Canonical connector ingress decision" \
  --summary "All accepted provider events now enter through service-canonical-ingestion." \
  --status "implemented" \
  --tags "marketing,ingestion,governance" \
  --evidence "commit abc123,test_contract_ingress"

The recorder:

rejects unsupported status labels;
rejects obvious secret material;
caps title/summary length;
inserts the newest record at the top of the bounded inbox;
rolls over first if the append would cross the warning threshold;
rebuilds the index;
runs strict validation.

Use records for decisions, durable defects, production state changes, and unresolved operator actions. Do not record routine commands or raw logs.

Lossless rollover

Preview:

python3 scripts/claude_memory.py rollover

Apply:

python3 scripts/claude_memory.py rollover --apply

The default is dry-run. The apply transaction:

obtains .claude/.runtime/claude-memory-rollover.lock;
reads exact source bytes;
computes SHA-256 and Git blob SHA-1;
writes the archive to a temporary file and atomically renames it;
re-reads and verifies exact bytes and Git identity;
moves the inbox into .claude/memory/inbox/YYYY-MM.md;
creates a bounded search-term/heading catalog and adds an immutable search_only module to the manifest;
renders the compact bootstrap template;
rebuilds the generated index;
runs strict validation;
restores original files and removes a newly created archive if any step fails.

Archive filenames include the date, detected version, and Git blob prefix. Existing paths are never overwritten with different bytes.

Manual routing

python3 scripts/claude_memory.py route \
  --prompt "Harden Shopify webhook replay and canonical KG lineage"

The output is suitable for a human or any non-Claude agent. It contains the mandatory authority order and selected modules.

Validation

python3 scripts/claude_memory.py status
python3 scripts/claude_memory.py check --strict
python3 scripts/claude_memory.py reindex
python3 -m unittest tests.test_claude_memory

Validation checks:

file thresholds;
manifest schema and unique module paths;
mandatory file existence;
bootstrap/index markers;
absence of bulk @ memory imports;
active-module limits;
required Claude Code hooks;
archive Git blob identity;
script presence.

Google Drive clone parity

GitHub is canonical. The Drive clone is a checksum-verified mirror.

Dry-run:

python3 scripts/claude_memory.py sync-drive

Apply:

python3 scripts/claude_memory.py sync-drive --apply

Verify:

python3 scripts/claude_memory.py check-drive

Target resolution order:

--target;
MIZOKI_DRIVE_CLONE;
approved local paths in manifest.json.

The sync copies only managed memory-system files, uses atomic writes, verifies SHA-256, never prunes unrelated Drive files, and writes .claude-memory-sync-receipt.json.

When the working repository already resolves to the Drive-clone directory, the command reports already-in-drive-clone and performs no duplicate copy.

Adding a new memory module

Create a focused file under .claude/memory/active/.
Add one manifest module with: - unique id; - path; - authority; - priority; - load_mode; - focused keywords; - useful path hints.
Add a path-scoped .claude/rules/*.md file only when file location is a strong routing signal.
Run reindex.
Test a positive and negative route.
Run strict validation.
Sync and verify the Drive clone.

Do not make every module always; that recreates the startup problem.

Promotion and retirement

Inbox → active: promote a still-relevant decision into a domain module.
Active → archive: archive when it is no longer operationally current.
Archive → active: never copy blindly; verify the current tree/live state, then write a new active record.
Delete: only duplicate/generated memory may be removed. Historical evidence remains recoverable.

Security and privacy

Never store secrets, access tokens, raw credentials, private keys, or unnecessary personal data in any memory layer. Memory files are committed and mirrored. Refer to secret names and audit IDs, not secret values.

Operational definition of done

The memory system is operational when:

the compact root and index pass limits;
the original blob identity validates;
hooks are installed;
routing selects expected modules;
unit tests pass;
Drive parity is either verified or explicitly reported as unavailable;
no historical archive is bulk-loaded by default.