Timmy_Foundation/hermes-agent
15
0
Fork 0
Code Issues 67 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

[EPIC] Unified Memory Architecture — Four-Tier System #239

New Issue
Open
opened 2026-04-09 00:40:59 +00:00 by Rockachopa · 0 comments
Rockachopa commented 2026-04-09 00:40:59 +00:00
Owner
Copy Link

Problem

Timmy has 7 disconnected memory systems producing knowledge that never reaches the agent at decision time:

  1. Built-in Memory (MEMORY.md/USER.md) — 2200+1375 chars, 99% full, always injected but tiny
  2. Holographic Fact Store (memory_store.db) — Full prefetch pipeline wired, 0 facts stored
  3. Mempalace (forge.json, mempalace.yaml) — Rich operational intelligence, ZERO code reads it
  4. Session Search (state.db, 8956 sessions) — Deep archive, only accessed by explicit tool call
  5. Cron Outputs — Operational data in flat files, stranded on disk
  6. Skills (200+) — Procedural knowledge, loaded by instruction not by relevance

Timmy starts every conversation as an amnesiac with 2200 chars of notes. The mempalace computes "491 open issues, top 3 priorities" every hour — and the agent can't access any of it without manually reading files.

Root Cause

No unified retrieval layer. Each system writes to its own store but there is no single "recall" operation that queries across all stores and injects relevant context before each turn.

Architecture: Four Memory Tiers

Tier Name What Store Injection
0 Identity Core identity, hard rules, user profile MEMORY.md/USER.md Always present in system prompt
1 Semantic Durable facts, decisions, preferences, architecture memory_store.db (holographic) prefetch() by relevance * trust * recency
2 Operational Fleet state, issue backlogs, health, cron results Mempalace files + cron outputs New OperationalMemoryProvider
3 Episodic Full conversation history state.db (sessions) Proactive FTS5 probe + auto-trigger

Design Principles

  1. Automatic, not conscious — knowledge surfaces without agent deciding to look
  2. Tiered by durability — hot/warm/operational/archival
  3. Sovereign — no cloud dependencies, all local SQLite/FTS5/files
  4. Honest about freshness — timestamps on everything, staleness warnings
  5. Quality over quantity — 5 relevant facts > 50 mediocre ones
  6. Don't poison durable memory with ephemeral data

Phases

  • Phase 1: Activate what exists (seed fact store, enable decay, tune prefetch)
  • Phase 2: Build operational bridge (mempalace → agent context)
  • Phase 3: Proactive episodic recall (auto-surface past sessions)
  • Phase 4: Memory hygiene (contradictions, trust calibration, pruning)
  • Phase 5: Integration testing and documentation

Success Criteria

  1. Relevant facts auto-injected every turn (not just 2200 chars)
  2. Operational intelligence visible without manual file reads
  3. Past conversations surface when contextually relevant
  4. Stale data timestamped, contradictions detected
  5. Zero cloud dependencies
  6. <200ms latency, <2000 tokens per turn overhead

Research

Full architecture doc: ~/.hermes/claude-code/memory-architecture-epic.md
Research notes: ~/.hermes/claude-code/agent_memory_research.md
Comparable systems studied: MemGPT/Letta, LangChain/LangGraph, CrewAI, AutoGen, Generative Agents (Stanford)

## Problem Timmy has 7 disconnected memory systems producing knowledge that never reaches the agent at decision time: 1. **Built-in Memory** (MEMORY.md/USER.md) — 2200+1375 chars, 99% full, always injected but tiny 2. **Holographic Fact Store** (memory_store.db) — Full prefetch pipeline wired, 0 facts stored 3. **Mempalace** (forge.json, mempalace.yaml) — Rich operational intelligence, ZERO code reads it 4. **Session Search** (state.db, 8956 sessions) — Deep archive, only accessed by explicit tool call 5. **Cron Outputs** — Operational data in flat files, stranded on disk 6. **Skills** (200+) — Procedural knowledge, loaded by instruction not by relevance Timmy starts every conversation as an amnesiac with 2200 chars of notes. The mempalace computes "491 open issues, top 3 priorities" every hour — and the agent can't access any of it without manually reading files. ## Root Cause No unified retrieval layer. Each system writes to its own store but there is no single "recall" operation that queries across all stores and injects relevant context before each turn. ## Architecture: Four Memory Tiers | Tier | Name | What | Store | Injection | |------|------|------|-------|-----------| | 0 | Identity | Core identity, hard rules, user profile | MEMORY.md/USER.md | Always present in system prompt | | 1 | Semantic | Durable facts, decisions, preferences, architecture | memory_store.db (holographic) | prefetch() by relevance * trust * recency | | 2 | Operational | Fleet state, issue backlogs, health, cron results | Mempalace files + cron outputs | New OperationalMemoryProvider | | 3 | Episodic | Full conversation history | state.db (sessions) | Proactive FTS5 probe + auto-trigger | ## Design Principles 1. Automatic, not conscious — knowledge surfaces without agent deciding to look 2. Tiered by durability — hot/warm/operational/archival 3. Sovereign — no cloud dependencies, all local SQLite/FTS5/files 4. Honest about freshness — timestamps on everything, staleness warnings 5. Quality over quantity — 5 relevant facts > 50 mediocre ones 6. Don't poison durable memory with ephemeral data ## Phases - **Phase 1:** Activate what exists (seed fact store, enable decay, tune prefetch) - **Phase 2:** Build operational bridge (mempalace → agent context) - **Phase 3:** Proactive episodic recall (auto-surface past sessions) - **Phase 4:** Memory hygiene (contradictions, trust calibration, pruning) - **Phase 5:** Integration testing and documentation ## Success Criteria 1. Relevant facts auto-injected every turn (not just 2200 chars) 2. Operational intelligence visible without manual file reads 3. Past conversations surface when contextually relevant 4. Stale data timestamped, contradictions detected 5. Zero cloud dependencies 6. <200ms latency, <2000 tokens per turn overhead ## Research Full architecture doc: `~/.hermes/claude-code/memory-architecture-epic.md` Research notes: `~/.hermes/claude-code/agent_memory_research.md` Comparable systems studied: MemGPT/Letta, LangChain/LangGraph, CrewAI, AutoGen, Generative Agents (Stanford)
Rockachopa added this to the Unified Memory Architecture milestone 2026-04-09 00:40:59 +00:00
Rockachopa added the epic:memory label 2026-04-09 00:40:59 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CI
Continuous integration, runners, workflow issues
 QA
Quality assurance, testing, production audit
 assigned-claw-code
Queued for Code Claw (qwen/openrouter)
 assigned-kimi
Task assigned to KimiClaw for processing
 blocked
Blocked by external dependency or merge conflict
 claw-code-done
Code Claw completed this task
 claw-code-in-progress
Code Claw is actively working
 duplicate
Duplicate of another issue
 epic
Epic - large feature with multiple sub-tasks
 epic:memory
Unified Memory Architecture epic
 gaming
Gaming agent capabilities
 infra
Infrastructure, VPS, DNS, deployment
 kimi-done
KimiClaw has completed this task
 kimi-in-progress
KimiClaw is actively working on this
 mcp
MCP (Model Context Protocol) tools & servers
 morrowind
Morrowind Agent gameplay & MCP integration
 needs-review
PR or issue requires reviewer sign-off before merge/close
 p0-critical
p1-important
phase:1-activate
Phase 1: Activate existing systems
 phase:2-operational
Phase 2: Operational memory bridge
 phase:3-episodic
Phase 3: Proactive episodic recall
 phase:4-hygiene
Phase 4: Memory hygiene and quality
 phase:5-integration
Phase 5: Integration and testing
 security
Security hardening, vulnerability fixes
 stale
No activity, pending triage or closure
 velocity-engine
Auto-generated by velocity engine
 wont-fix
Closed as intentionally not fixing — explicit descope
No Label epic:memory
Milestone
No items
No Milestone Unified Memory Architecture
Projects
Clear projects
No project
Assignees
Clear assignees
Rockachopa Timmy allegro antigravity bezalel claude claw-code codex-agent ezra gemini google grok hermes kimi manus perplexity sonnet
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Timmy_Foundation/hermes-agent#239
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?