Structured Memory

# 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`
-...

# Structured Memory

Structured Memory is an OpenClaw skill for long-horizon agent memory maintenance.

It keeps `memory/YYYY-MM-DD.md` as the source of truth, then builds a structured retrieval layer on top of it:

- rebuildable indexes by date, module, and entity
- execution-critical fact extraction
- object-style fact cards for recall
- card-first retrieval for paths, services, IDs, endpoints, repositories, and other operational facts

## Current release

- Version: `1.0.1`
- Regression baseline: `206 / 206 passing`

## What this repository contains

- `skills/structured-memory/` — the published skill package
- `projects/structured-memory-spec.md` — design/spec notes
- `projects/structured-memory-stable-baseline-2026-03-10.md` — frozen baseline snapshot

## Core idea

Structured Memory does **not** replace daily memory.
It depends on daily memory and improves retrieval on top of it.

Source of truth:

- `memory/YYYY-MM-DD.md`

Structured layers built from it:

- `memory-index/`
- `memory-modules/`
- `memory-entities/`
- `critical-facts/`
- `critical-facts/cards/`

## Typical workflow

### 1. First-time setup

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

### 2. Daily maintenance

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

### 3. Validation / diagnostics

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

## Default operating model

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.

## Publishing

Published skill bu...