structured-memory

name

structured-memory

description

Build and maintain a structured memory system for OpenClaw workspaces using layered storage: daily memory as the source of truth, domain/module/entity/tag indexing, critical-facts extraction, and retrieval planning. Use when designing, initializing, updating, or operating a memory system that must scale across work topics such as business, finance, legal, HR, projects, operations, tech, routines, and personal context.

Structured Memory

Version: 1.0.1

Use this skill to initialize and maintain a layered memory system in the OpenClaw workspace.

What it does

• Uses memory/YYYY-MM-DD.md as the source of truth
• Builds rebuildable indexes by date, module, and entity
• Extracts reusable execution-critical facts into critical-facts/
• Rebuilds object-style cards under critical-facts/cards/
• On first initialization, backfills existing memory/*.md history automatically
• Maintains a frozen summary baseline with preview + topic_summaries

Default operating rule

For agents that have this skill installed, structured-memory should not be treated only as an on-demand utility. When the day produced meaningful task progress, decisions, blockers, risks, reusable execution-critical facts, or other meaningful updates to memory/YYYY-MM-DD.md, the agent should treat structured-memory rebuild as part of its default memory maintenance workflow.

Work-cycle maintenance rule

After meaningful updates are written into memory/YYYY-MM-DD.md, the agent should normally rebuild the current day into the structured layer before the work cycle ends. This keeps indexes, modules, entities, critical-facts, and cards aligned with the source-of-truth daily memory.

Core rules

1. Treat memory/YYYY-MM-DD.md as the source of truth.
2. Keep first-level domain fixed and small.
3. Create second-level module files only on demand.
4. Prefer entities for stable objects and free_tags for one-off concepts.
5. Store reusable execution-critical facts under critical-facts/.
6. Never store high-sensitivity secrets in plain text unless the user explicitly requires it.
7. Indexes are rebuildable caches, not the truth.
8. A short daily preview is only for quick glance; it must not replace topic-level summaries for multi-topic days.

Fixed first-level domains

Use these exact domains:

• strategy
• business
• organization
• finance
• legal
• project
• operations
• tech
• routines
• personal
• meta
• misc

When creating modules

Before creating a new module:

1. Check whether an equivalent module already exists.
2. Check whether the concept should instead be an entity.
3. Check whether the concept is too specific and should remain a free tag.
4. Create a module only if it is a reusable topic bucket.

Retrieval order

Default retrieval order:

1. MEMORY.md
2. projects/*.md
3. critical-facts/cards/ for execution-critical lookups about servers, services, paths, IDs, endpoints, repositories, dependencies, or stable operational objects
4. critical-facts/*.md for raw fact scanning when the cards are missing or too sparse
5. memory-index/by-date.json
6. memory-modules/ and memory-entities/
7. candidate memory/YYYY-MM-DD.md files

Recall priority rule

When the agent needs to recall cross-day work, historical decisions, stable identifiers, paths, endpoints, repositories, service names, project dependencies, or other execution-critical facts, it should prefer checking the structured-memory layer before relying only on current chat context.

Files to consult

Read these references as needed:

• references/taxonomy.md for domain and module rules
• references/write-rules.md for write/update behavior
• references/retrieval-planner.md for query routing
• references/index-schema.md for JSON and entry schemas
• references/critical-facts-policy.md for sensitive-fact handling

Scripts

Operating modes

1. First-time setup

Run once when enabling the skill in a workspace:

python3 skills/structured-memory/scripts/init_structure.py

2. Daily maintenance

Run after meaningful updates to the current day:

python3 skills/structured-memory/scripts/rebuild_one_day.py YYYY-MM-DD

3. Validation / diagnostics

Use when checking stability or searching execution-critical facts:

python3 skills/structured-memory/scripts/check_idempotency.py YYYY-MM-DD
python3 skills/structured-memory/scripts/search_critical_facts.py <query>

• scripts/init_structure.py initializes the workspace structure safely and, on first run, backfills existing memory/*.md history into indexes / critical-facts / cards unless explicitly skipped.
• scripts/parse_daily_memory.py converts a daily memory file into a normalized index entry, supporting both structured entries and legacy bullet-style notes.
• scripts/upsert_by_date_index.py updates memory-index/by-date.json deterministically.
• scripts/update_topic_indexes.py appends module and entity index entries from a parsed daily memory result.
• scripts/rebuild_one_day.py reparses a single daily memory file and refreshes its by-date/module/entity indexes plus the corresponding critical-facts/ entries for that day.
• scripts/check_idempotency.py verifies that rebuilding the same day twice produces a stable result.
• scripts/summarize_daily_memory.py generates the frozen summary layer in the current stable baseline: short preview plus topic_summaries for multi-topic days.
• scripts/extract_critical_facts.py extracts reusable execution-critical facts (IPs, paths, endpoints, service names, stable ids) and can write them into critical-facts/*.md.
• scripts/rebuild_critical_fact_cards.py rebuilds object-style fact cards under critical-facts/cards/ by grouping facts around related entities/projects. Its parser is intentionally tolerant of malformed property lines, empty values, fullwidth colons, and odd spacing so one bad fact line does not crash the whole rebuild.
• scripts/search_critical_facts.py searches critical-fact cards first, then raw critical-facts/*.md files.
• tests/run_tests.py runs the regression suite across representative memory samples.

Common commands

python3 skills/structured-memory/tests/run_tests.py
python3 skills/structured-memory/scripts/init_structure.py
python3 skills/structured-memory/scripts/rebuild_one_day.py 2026-03-10
python3 skills/structured-memory/scripts/check_idempotency.py 2026-03-10
python3 skills/structured-memory/scripts/search_critical_facts.py structured-memory

Source-of-truth reminder

Do not skip or weaken memory/YYYY-MM-DD.md. Structured-memory depends on daily memory and improves retrieval on top of it; it does not replace the source-of-truth record.

Use scripts for deterministic structure work; use manual edits for small, obvious updates.

Stability note

As of 2026-03-10, 1.0.1 is the current published baseline. The current implementation is frozen after the regression suite reached 206/206 passing. Before changing summary behavior again, update tests first and preserve compatibility with preview + topic_summaries.