Skill: chauncyzbc/structured-memory (version 1.0.1)

--- 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: ```bash python3 skills/structured-memory/scripts/init_structure.py ``` #### 2. Daily maintenance Run after meaningful updates to the current day: ```bash python3 skills/structured-memory/scripts/rebuild_one_day.py YYYY-MM-DD ``` #### 3. Validation / diagnostics Use when checking stability or searching execution-critical facts: ```bash 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 ```bash 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`.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)