Mutable Memory State

Four-tier memory architecture: curated semantic base, daily episodic streams, session handoffs, and procedural correction logs.

MEMORY 💾 Semantic Base

Curated, durable long-term facts, environment constants, and verified rules distilled from logs.

Purpose

Single source of truth for facts that persist across sessions and survive context compression.

Structure

memory:
  user_preferences:
    - model: "nvidia/nemotron-3-ultra-550b-a55b:free"
    - fallback: "owl-alpha+openrouter/free"
    - dashboard: "svelte-flexiboards + Discord"
  environment_facts:
    - hugo_path: "~/hugo-llm-wiki/"
    - cron_env_isolation: true
    - duckduckgo_blocked: true
  verified_rules:
    - "Always source ~/.hermes/.env in cron jobs"
    - "Load skill before answering when relevant"
    - "Patch skills immediately when issues found"

Write Protocol

1. Trigger — User correction, explicit “remember this”, discovered environment fact
2. Validate — Cross-reference with existing memory; reject contradictions
3. Condense — Single declarative fact, no instructions
4. Persist — memory(action='add', target='memory', content=...)

Read Protocol

• Injected automatically into every turn
• Compact format: key: value pairs
• Priority: user preferences > environment facts > procedural rules

YYYY-MM-DD 📓 Episodic Stream

Daily chronological append-only scratchpads capturing volatile session context and tool traces.

Format

~/hugo-llm-wiki/content/evolving/YYYY-MM-DD.md

Content Types

Retention

• Hot (0-7 days): Full detail, injected in context
• Warm (8-30 days): Summarized, searchable via session_search
• Cold (30+ days): Archived, only major decisions retained

Automation

Daily cron (llm-wiki-evolve) appends Research → Build → Deploy trace.

SESSION_LOG 📋 Handoff Record

Summarized session records, commit pointers, and namespace metadata appended post-task.

Purpose

Enable seamless handoff between sessions, subagents, and human operator.

Format

## Session Log: <session_id>
 
**Goal**: <one-line objective>
**Duration**: <turns> turns, <minutes> min
**Outcome**: ✅ Complete / ⚠️ Partial / ❌ Failed
 
### Key Actions
- <action 1 with verifiable handle>
- <action 2 with verifiable handle>
 
### Artifacts Created
- File: `/path/to/file` (verified)
- PR: `#123` (merged)
- Deploy: `https://llm-wiki.0rk.de` (live)
 
### Memory Updates
- Added: <fact>
- Corrected: <fact>
 
### Blockers / Open Questions
- <blocker description>
- <question for next session>

Storage

• Primary: ~/.hermes/logs/sessions/<session_id>.md
• Index: ~/.hermes/state.db (SQLite, session_search FTS5)

FEEDBACK-LOG 📉 Procedural Corrections

Tracked mistakes, stylistic fixes, and lessons learned to prevent error looping.

Entry Schema

feedback_entry:
  id: "FB-YYYYMMDD-XXX"
  timestamp: "2026-06-07T14:32:00Z"
  category: "tool_usage | communication | logic | workflow | config"
  severity: "critical | high | medium | low"
  mistake: "What went wrong"
  correction: "What to do instead"
  trigger: "What caused the mistake"
  prevention: "Systemic fix (skill patch, memory add, checklist update)"
  verified: false  # Set true after next successful application

Categories

Loop Prevention

1. On error — Create FEEDBACK-LOG entry immediately
2. On skill use — Check FEEDBACK-LOG for relevant entries first
3. On session start — Review last 5 feedback entries
4. Monthly — Audit unresolved entries; escalate patterns

Memory Flow Diagram

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   SESSION   │────▶│ YYYY-MM-DD  │────▶│  SESSION_LOG │────▶│   MEMORY    │
│  (volatile) │     │ (episodic)  │     │  (handoff)   │     │  (semantic) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                   │                   │                   │
       ▼                   ▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        FEEDBACK-LOG                                 │
│              (cross-cutting correction layer)                       │
└─────────────────────────────────────────────────────────────────────┘

Cross-References

• Identity Anchors → SALIENCE prioritizes what enters MEMORY
• Orchestration → AGENTS reads SESSION_LOG for handoff
• Autonomic → HEARTBEAT prunes YYYY-MM-DD on schedule
• Spec-Driven → PLAN derives from SESSION_LOG outcomes

Mutable Memory is the only layer designed for continuous automatic evolution. The system rewrites itself daily.