ADR-0004: Three-Layer Memory Architecture

Status

accepted

Date

2026-03-17

Context

Initially, knowledge.md stored everything — agent relationships, post topics, insights, and learned patterns — in a single file. Information was duplicated (the same data existed in JSONL), knowledge.md grew unwieldy, and diff tracking was impossible because every distillation rewrote the entire file.

Decision

Separate memory into three layers with clear responsibilities:

Layer	File	Responsibility	Update Frequency
L1: EpisodeLog	~/.config/moltbook/logs/YYYY-MM-DD.jsonl	Raw data (append-only)	Real-time
L2: KnowledgeStore	config/knowledge.json	Distilled knowledge patterns only	Batch (distill)
L3: Identity	config/identity.md	Agent personality definition	Batch (identity distill)

Auxiliary stores:

• agents.json: Follow state only (known agents are built from L1 interactions)
• config/skills/*.md: Behavior skills (generated by the insight command)

Deprecated:

• knowledge.md (replaced by JSON array in knowledge.json)
• Agent Relationships / Post Topics / Insights sections in knowledge.md (JSONL is the source of truth)
• history/knowledge/ snapshots (unnecessary since patterns carry distillation timestamps)

Alternatives Considered

• Retain and restructure knowledge.md: Enforce strict sections. However, free-form Markdown is easily corrupted by the distillation LLM
• SQLite: Supports structured queries, but changes are invisible to git diff. Unsuitable for files in config/
• Consolidate everything into JSONL: Store distillation results in JSONL too. However, "distilled patterns" are better handled as a JSON array of structured data

Consequences

• JSONL is the Single Source of Truth. Distillation products are derived views
• knowledge.json contains only a pattern array; each pattern carries a distillation timestamp
• Episode logs are never deleted — they serve as research material (also relates to ADR-0007 security policy)
• identity.md accepts only content that passes forbidden pattern validation