# Clavue Agent OS Memory Architecture v1

**Status**: Draft / Phase 0 Target
**Date**: 2026-06-01
**Owner**: Grok (Route C initiative)
**Related Interfaces**: `src/agent-os/memory/interfaces.ts`

---

## 1. Executive Summary

This document defines the target memory architecture for Clavue under **Route C** — a radical but deliberate paradigm shift from a transcript-centric AI coding CLI to a true **Agent Operating System (Agent OS)**.

The core thesis:

> In long-horizon, high-stakes software development, the linear conversation transcript is no longer a viable primary source of truth. Instead, persistent, structured, queryable, versioned state + knowledge graph + event sourcing must become first-class citizens. The LLM primarily reasons over projections and views of this state, while the conversation history becomes an immutable audit log.

This architecture aims to solve the fundamental scalability, performance, explainability, and continuity problems observed in current long-context coding agents (including Clavue's own challenges with deep context, slow compaction, and "Pontificating/Unravelling" latency).

---

## 2. Current Baseline (Why Route C Is Necessary)

From systematic exploration of the codebase, Clavue's current architecture is a sophisticated but fundamentally **history-centric hybrid**:

### Strengths (We Already Have Good Foundations)
- Explicit, human-readable memory artifacts (handoff sidecars with `CompactStateV1`)
- Structured state tracking (WorkRuntime + WorkEventBus)
- Multi-layer compaction (micro, reactive, auto, emergency)
- File-backed auto memory (memdir)
- Long-term distillation (CONTEXT.md)
- Pinned context as hard constraints during compaction

### Fundamental Limitations
- The **Message[] transcript** remains the dominant source of truth passed to the LLM every turn.
- Compaction physically rewrites history (destructive to prompt caching and precise recovery).
- Memory layers (handoff, memdir, work, pinned, distill, SessionMemory) exist in parallel with insufficient unified governance.
- The model is forced to carry both "thinking" and "memory management" burden simultaneously.
- Context growth still leads to severe latency and quality degradation (observed with strong models like gpt-5.5 and DeepSeek-v4).

These limitations are not bugs in implementation — they are the natural ceiling of a transcript-first architecture when pushed to real long-horizon work.

---

## 3. Vision & Guiding Principles

### Primary Truth Shift
- **Before (History-centric)**: The growing conversation transcript + occasional summaries is "what the agent knows."
- **After (State-centric Agent OS)**: A living, queryable, versioned Project State + Knowledge Graph is "what the agent knows." The transcript is "what was said and done."

### Core Principles (Highest Standard)
1. **State > History**
   Structured, typed, mutable state with clear semantics is the default reasoning substrate.

2. **Event Sourcing as Foundation**
   All meaningful changes are recorded as immutable events. State is derived via projections.

3. **Explicit Memory Governance**
   A dedicated (lightweight) Memory Governor / Agent makes deliberate decisions about what to remember, compress, promote, forget, or project — instead of relying solely on token thresholds.

4. **Multi-Layer, Multi-Model Memory**
   Different memory operations use different model tiers and different storage substrates (in-memory, disk, graph, vector).

5. **Human + Machine Readable**
   Memory artifacts must remain useful to both humans and agents (continuing the spirit of explicit handoff sidecars).

6. **Projections Over Raw Context**
   The model rarely sees the raw full history. It sees task-specific, high-signal projections.

7. **Lifecycle & Ownership**
   Every piece of memory has clear ownership, lifetime, and versioning.

---

## 4. Target Architecture — Layered Memory OS

### 4.1 Memory Layers (from short-term to long-term)

| Layer                    | Purpose                              | Primary Form                  | Mutability     | Model Tier     | Query Style          |
|--------------------------|--------------------------------------|-------------------------------|----------------|----------------|----------------------|
| **Ephemeral Working Memory** | Current turn reasoning              | Small recent events + scratch | High           | Strong model   | Direct               |
| **Episodic Memory**      | Completed tasks, phases, decisions  | Structured sidecars + events  | Append-only    | Medium         | Time + Scope         |
| **Procedural State**     | Live tasks, plans, work units       | Typed state machines          | Mutable        | N/A (structured) | Exact + Graph     |
| **Semantic / Knowledge Graph** | Long-term facts, architecture, relationships | Entities + Relations       | Mutable        | Light + Strong | Graph + Vector       |
| **Distilled Long-term**  | High-level principles & architecture| Structured summaries          | Slowly mutable | Strong (rare)  | Semantic + Structured|
| **Audit Transcript**     | Verbatim conversation history       | Immutable event log           | Append-only    | N/A            | Full-text / Time     |

### 4.2 Key Subsystems

- **Event Log** (`EventLog` interface): The single source of all change. Immutable, append-only.
- **State Store** (`StateStore`): The current materialized state, derived from events.
- **Knowledge Graph** (`KnowledgeGraph`): Semantic + structural long-term memory.
- **Projection Engine** (`ProjectionEngine`): Generates task-optimized views (e.g., "current coding context", "recent decisions", "open risks").
- **Memory Governor** (`MemoryGovernor`): The brain of the memory system. Decides when and how to promote, compress, forget, or project information. Can be rule-based + model-assisted.
- **Legacy Bridge**: Maintains compatibility with existing transcript-based flows during migration.

---

## 5. Migration Strategy (Highest Standard = Pragmatic Radicalism)

We will **not** do a big-bang rewrite.

### Phase 0: Foundations (Now – 2 months)
- Define and stabilize the core interfaces (done: `interfaces.ts`).
- Create the formal **Agent OS Memory Architecture Spec v1** (this document + follow-ups).
- Introduce a `MemoryGovernor` prototype that can observe and influence existing compaction flows without replacing them yet.
- Strengthen PinnedContext and WorkRuntime as "first-class state" rather than attachments.

### Phase 1: Dual-Track State Elevation (2–5 months)
- Run the old transcript-centric path and the new state-centric path in parallel.
- Gradually move high-value state (plans, tasks, decisions, architecture components) into the new `StateStore` + `KnowledgeGraph`.
- Start generating **Projections** for the model instead of (or in addition to) raw post-compaction messages.
- Existing `handoff` sidecars and `Work` units become first-class citizens in the new system.

### Phase 2: Governor Takes Control (5–8 months)
- The Memory Governor becomes the primary decision maker for when and how to compact, externalize, or promote information.
- Traditional LLM-based compaction becomes one possible strategy among several (state diff + projection, graph update, etc.).
- Transcript is still maintained for compatibility and human review, but is no longer the main thing sent to the model every turn.

### Phase 3: Full Agent OS Maturity (8+ months)
- Multiple specialized projections per turn.
- Rich time-travel and audit capabilities.
- Memory operations exposed as first-class tools/APIs for sub-agents and plugins.
- External systems (Git, issues, design docs) deeply integrated as sources/sinks of the Knowledge Graph.

---

## 6. Success Metrics (Per Phase)

**Phase 0**:
- Clear, stable interfaces defined and reviewed.
- At least one existing high-quality component (e.g., WorkRuntime or handoff) wrapped behind the new abstractions.

**Phase 1**:
- Measurable reduction in average context tokens sent to the model during normal coding.
- First successful "state projection" used in a real user session instead of raw transcript.

**Phase 2**:
- Significant reduction in "Waiting for model" timeout events during long sessions.
- Memory Governor making non-trivial autonomous decisions (e.g., promoting important decisions to the graph without user intervention).

**Phase 3**:
- Clavue can maintain coherent, high-quality work across weeks/months with dramatically lower per-turn token cost than pure long-context approaches.
- External contributors and sub-agents can usefully operate against the memory system without reading the full transcript.

---

## 7. Risks & Mitigations (Highest Standard)

- **Migration Complexity** → Strong Legacy Bridge + long dual-track period.
- **Performance Regressions During Transition** → Rigorous benchmarking at each phase gate.
- **Over-abstraction** → Ruthless focus on concrete user value at every step; no abstraction without a driving use case.
- **Loss of "Chat Feel"** → Preserve excellent conversational UX while the backend memory model changes.

---

## 8. Immediate Next Steps (Highest Priority)

1. Flesh out the detailed **Agent OS Memory Architecture Spec v1** (this document will be iterated heavily).
2. Implement a minimal but production-grade `MemoryGovernor` prototype that can sit alongside the existing compaction system.
3. Begin mapping the highest-leverage existing components (WorkRuntime, handoff sidecars, pinnedContext) to the new interfaces.
4. Define the first meaningful Projection (e.g., "Current Coding Context Projection").

---

**This is the highest-standard blueprint for Route C.**

We are not doing incremental improvement. We are deliberately choosing the hardest, highest-reward path — turning Clavue into a genuine Agent Operating System with memory as its architectural heart.

The interfaces in `src/agent-os/memory/interfaces.ts` are the first concrete artifact of this journey.

Ready for the next concrete step (Spec v1 writing, Governor design, or component mapping)? Tell me where to go next.