Kiro Local Memory Use Case

• Use case ID: memory.kiro-local
• Protocol: memory@0.1.0
• Evidence: field-tested
• Conformance: mapped — historical lifecycle evidence maps through memory:L4 against memory@0.1.0; the memory@0.2.0 withdrawal/erasure contract and current item schema were not revalidated
• Validation scope: deployed local archive/autodream workflow and review path; not re-executed during the 2026-08-13 withdrawal-protocol alignment review
• Reproducibility: partial — architecture and procedures are documented; exact local scripts are not included here
• Level namespace: memory
• Last reviewed: 2026-08-13

1. Context

This use case describes a local .kiro/memories memory system for cross-session persistent agent memory on macOS.

The goal is to let an AI agent keep useful memory across sessions while automatically maintaining that memory without requiring the human to manually curate files every day.

The design is a practical implementation of Agent-first Memory Architecture.

Protocol alignment note

This deployment predates memory@0.1.0. Its observed archive, distillation, index, topic, log, and review lifecycle informed the protocol, but the deployed artifacts described here still use legacy additive updates and free-form cleanup markers. Before claiming current memory@0.2.0 conformance, migrate captures to stable id, kind, Source, and subject for state; replace free-form cleanup markers with the closed Status vocabulary; validate exact-subject non-destructive supersede; and implement withdrawal routing, control records, anti-resurrection, and authorized-erasure receipts. The evidence label describes real operation, not schema certification.

2. Design philosophy

This system was informed by three design influences:

1. Karpathy's LLM Wiki pattern — a wiki-like index as the entry point for compiled agent knowledge.
2. An earlier OpenClaw autodream contribution reviewed during implementation — a staged memory pipeline where raw memory is preserved before distillation. This page does not copy or redistribute that contribution.
3. Small hot index + deeper topic pages — separating frequently loaded navigation from warm/cold knowledge bodies.

These influences explain design provenance; they are not runtime evidence or dependencies.

The core idea:

Give the AI agent persistent cross-session memory that can maintain itself automatically, without requiring the human to manually organize notes.

3. Directory structure

~/.kiro/memories/
├── conventions.md     -> symlink -> automation repository stable rules (rarely changed)
├── memory.md          # daily inbox / hot working memory, written during sessions
├── log.md             # operation timeline for archive/dream/review events
├── index.md           -> symlink -> automation repository wiki index
├── archive/           -> symlink -> automation repository daily archives
│   ├── 2026-05-02.md
│   ├── 2026-05-03.md
│   └── ...
└── topics/            -> symlink -> automation repository topic pages
    ├── memory-system-design.md
    ├── steering-design-guide.md
    └── openab-deployment.md

4. Layering model

Why conventions is Hot (not Warm)

The decision tree from the architecture doc asks: "If this is not loaded, will the agent's next response or action likely be wrong?"

For conventions, the answer is yes. Without loading conventions, the agent may:

• Use the wrong git identity
• Push with wrong HOME (sandbox vs real)
• Skip mandatory security scans
• Violate workflow mandates

Therefore conventions must be loaded via agent resource (same mechanism as steering), not via index.md reference. This ensures it is always present regardless of context pressure.

5. Version-control strategy

Structural memory files are symlinked into a separate automation repository:

• conventions.md
• index.md
• archive/
• topics/

These files are useful across machines and should be synchronized.

High-frequency local files stay local:

• memory.md
• log.md

They are temporary, noisy, and change often. Keeping them out of version control avoids churn and prevents the repo from becoming a raw session dump.

6. AutoDream mechanism

Two scheduled jobs run through macOS launchd.

launchd is preferred over cron because cron does not wake a sleeping Mac, while launchd with StartCalendarInterval can run after wake.

Stage 1: auto-archive, daily 07:30

This stage is pure shell and does not use AI.

Steps:

1. Check whether memory.md has substantive content, ignoring blank lines, headings, and comments.
2. If content exists, move or append it to archive/YYYY-MM-DD.md.
3. Recreate a blank memory.md with the current day's header.
4. Append an archive record to log.md.
5. Rotate log.md when it exceeds the retention window, for example keeping the latest 100 entries.

Rationale:

Archiving is mechanical. It should not depend on model judgment. Raw memory must be preserved before AI transforms it.

Stage 2: auto-dream, daily 07:40

This stage invokes AI to distill memory.

The steps below describe the deployed legacy behavior. The add or revise wording and free-form [待清理] marker are evidence of the earlier binding, not recommendations for current memory@0.2.0; use the migration requirements in the Protocol alignment note before adopting them.

Execution mode:

kiro-wrap chat --no-interactive --trust-all-tools

Steps:

1. Check whether today's archive exists; skip if there is nothing to process.
2. Build a prompt instructing the AI to read the archive and existing index.md.
3. Ask the AI to:
   • Extract long-term valuable knowledge from the archive.
   • Update index.md.
   • Prefer additive updates: add or revise, but do not delete.
   • Mark stale entries as [待清理].
   • Preserve source-date markers on each item.
   • Keep index.md under roughly 200 lines.
   • Split a topic into topics/ when it accumulates more than about 5 useful entries.
   • Update a “recent activity” section, keeping about the latest 10 items.
4. Append a dream record to log.md.

7. Flow

Daytime usage                    07:30                07:40
────────────────────────────────────────────────────────────
sessions write memory.md   →   archive moves it   →   AI distills index/topics
                              (shell)                 (kiro-wrap)

Output:

• archive/YYYY-MM-DD.md
• recreated empty memory.md
• updated index.md
• updated topics/*.md when needed
• log.md operation trace

8. Key design decisions

8.1 Steering, conventions, and memories are separate

Steering stores static specifications:

WHAT / HOW (system-level directives)

Conventions store stable behavioral rules:

WHAT IS ALWAYS TRUE (identity, security, workflow mandates)

Memories store dynamic experience:

WHAT HAPPENED / WHAT WAS LEARNED

They should not be mixed. Autodream maintains memories but never touches steering or conventions.

8.2 Sub-agents mount memory selectively

Not every sub-agent should see all memory.

Memory visibility should be configured through resources or equivalent capability boundaries. Agents should receive only the memory layer relevant to their role.

8.3 launchd scripts must set PATH

launchd does not load shell profiles. Scripts should explicitly export paths such as:

~/.local/bin
~/.cargo/bin
/opt/homebrew/bin

8.4 Auto-dream must fix HOME when needed

If Kiro's sandbox profile changes HOME, auto-dream should explicitly set:

HOME="$REAL_HOME"

before invoking kiro-wrap.

9. Review entry point

The system preserves an explicit manual audit path:

review memory

A review should inspect:

• stale items
• duplicate entries
• index bloat
• missing source dates
• topic pages that should be split or merged
• memories that should or should not be promoted to conventions or steering

10. Evidence boundary

What this use case supports

• A real macOS binding used separate inbox, archive, index, topics, and operation log surfaces.
• Separating mechanical archive from AI distillation exposed reusable launchd and environment lessons.
• A manual review entry point remained necessary even with scheduled maintenance.

What it does not support

• End-to-end conformance with the current memory@0.2.0 item, withdrawal, and erasure contract.
• Current runtime health; the deployment was not re-executed during this review.
• Reproduction from this page alone; exact scripts and private environment assets are omitted.

11. Essence

The system can be summarized as:

Daytime human-agent collaboration creates memory.
Nightly archive preserves it.
Morning AI distillation extracts long-term knowledge.
The result becomes a wiki-like memory system.

Humans do not need to manually organize daily notes, but they keep an explicit audit entry point.