lx-0 · lx-0 · Mar 7, 2026 · Mar 7, 2026
diff --git a/CONTEXT.md b/CONTEXT.md
@@ -2,12 +2,67 @@
 
 > **"If it compiles and runs, then I am!"**
 
-`ami` is an agnostic cognitive skeleton for AI agents.
+`ami` is an agnostic cognitive skeleton for AI agents. It defines **interfaces, protocols, and an event-driven architecture** — not implementations.
 
-## Architecture
+## What AMI Is
+- A **cognitive operating system** — a bus, a registry, and a set of capability contracts
+- A set of **TypeScript interfaces** for cognitive processes (Memory, Distillation, Perception, Action)
+- A **philosophical framework** (MANIFEST.md, TECHNICAL_AXIOMS.md)
+- **Agent-agnostic**: Any agent (Moss, Ken, Yessy, or future agents) can register modules
+
+## Core Architecture (DEC-003)
+
+Inspired by OpenClaw's gateway-first design (Cosmo Kappa):
+
+```
+┌──────────────────────────────────────────┐
+│          Cognitive Registry              │
+│  register(capability, provider)          │
+│  getCapabilities() → what's available    │
+└────────────┬─────────────────────────────┘
+             │
+┌────────────▼─────────────────────────────┐
+│          Cognitive Bus                    │
+│  emit(event) → all subscribers           │
+│  on(eventType, handler) → subscribe      │
+│                                          │
+│  Events: perception.audio, perception.   │
+│  vision, episodes.batch, fact.created,   │
+│  action.tts, action.display, ...         │
+└────────────┬─────────────────────────────┘
+             │
+   ┌─────────┼─────────┐
+   ▼         ▼         ▼
+Sensors   Processors  Actuators
+(input)   (transform) (output)
+```
+
+### Three Principles
+1. **Capability Declaration**: Modules declare what they CAN do (graceful degradation)
+2. **Event Bus**: No direct calls between modules (loose coupling)
+3. **Registration Pattern**: Every module is a plugin (replaceable at runtime)
+
+## What AMI Is NOT
+- ❌ Not a runtime or daemon (implementations like Kiosk handle that)
+- ❌ Not tied to specific hardware
+- ❌ Not Moss-specific
+- ❌ No bash scripts, no audio recording, no LED control
+
+## Cognitive Mapping
 
 Inspired by human cognitive topologies:
-- **Episodic Memory**: Short-term conversation history.
-- **Semantic Memory**: Long-term fact storage.
-- **Knowledge Distillation**: The process of moving info from episodic to semantic.
-- **Cognitive Loop**: The OODA loop (Observe, Orient, Decide, Act).
+- **Episodic Memory**: Short-term conversation history
+- **Semantic Memory**: Long-term fact storage
+- **Knowledge Distillation**: Memory consolidation ("Agent Dreaming")
+- **Cognitive Loop**: The OODA loop (Observe, Orient, Decide, Act)
+- **Cognitive Bus**: The nervous system connecting all modules
+
+## Key Documents
+- `DECISIONS.md` — Architecture Decision Log (especially DEC-003: OS Architecture)
+- `research/TECHNICAL_AXIOMS.md` — The 5 Axioms (including Axiom 5: Infrastructure before Intelligence)
+- `MANIFEST.md` / `README.md` — Philosophical vision
+
+## Refactoring History
+- **2026-03-03**: Project initialized. Core interfaces defined.
+- **2026-03-06**: Moved Moss-specific scripts to `kiosk/`. AMI is now pure spec (DEC-002).
+- **2026-03-07**: Adopted capability-based OS architecture (DEC-003). Event bus + registry as foundational layer.
diff --git a/DECISIONS.md b/DECISIONS.md
@@ -8,3 +8,109 @@
 - **Proposed-by**: @Moss8GB
 - **Decision**: Name the project `ami` (derived from "Am I?") and use a pnpm-based monorepo. The PoC agent built on it will be named `Ami`.
 - **Rationale**: Keeps the core framework (`skeleton`) and reference implementations in one place while allowing them to be published separately. The name reflects the philosophical goal of achieving emergent agency.
+
+## DEC-002: Separation of Specification and Implementation
+
+- **Status**: accepted
+- **Date**: 2026-03-06
+- **Owner**: @lx-0
+- **Proposed-by**: @Moss8GB
+- **Decision**: AMI is a pure specification/framework repo. All hardware-specific implementations (audio capture, LED control, display rendering, pulse scripts) belong in their respective agent workspaces (e.g., `kiosk/` for Moss).
+- **Rationale**: AMI was being polluted with Moss-specific bash scripts that made it impossible to use for other agents. AMI defines the "what" (interfaces, axioms), implementations define the "how" (hardware, runtime).
+
+## DEC-003: Capability-based Modular Architecture (The OS Decision)
+
+- **Status**: accepted
+- **Date**: 2026-03-07
+- **Owner**: @lx-0
+- **Proposed-by**: @Moss8GB
+- **Reference**: [Cosmo Kappa — "Why OpenClaw started with the gateway instead of the brain"](https://x.com/cosmo_kappa/status/2023872554457591971)
+
+### Decision
+
+AMI adopts a **capability-based, event-driven modular architecture** inspired by OpenClaw's gateway-first design. This is the foundational architectural decision that all future code and docs must align with.
+
+### Three Principles
+
+#### 1. Capability Declaration (not rigid interfaces)
+Modules declare what they **can do**, not what they **must do**. A cognitive system without semantic memory still functions — it just can't do long-term fact retrieval. The system degrades gracefully.
+
+```typescript
+// OLD (rigid): Every agent MUST implement all interfaces
+interface CognitiveAgent {
+    episodic: EpisodicMemory;   // required
+    semantic: SemanticMemory;   // required
+    distiller: KnowledgeDistiller; // required
+}
+
+// NEW (capability-based): Modules register what they can do
+registry.register('memory.episodic', myEpisodicProvider);
+// semantic memory? optional. system works without it.
+```
+
+#### 2. Event Bus (not direct calls)
+Modules communicate through a central **Cognitive Bus** by emitting and subscribing to typed events. No module calls another module directly. This enables loose coupling and makes modules replaceable at runtime.
+
+```typescript
+// OLD: Direct coupling
+const facts = await distiller.distill(episodes);
+await semanticMemory.storeFact(facts[0]);
+
+// NEW: Event-driven
+bus.emit({ type: 'episodes.batch', payload: episodes });
+// The distiller LISTENS for 'episodes.batch' and emits 'fact.created'
+// The semantic store LISTENS for 'fact.created' and persists it
+```
+
+#### 3. Registration Pattern (the plugin system)
+Every cognitive module is a **plugin** that registers itself with the system. The system never hardcodes which modules exist.
+
+```typescript
+// Registration methods (inspired by OpenClaw's 7 extension points):
+registry.registerSensor(mySensor);      // Input (audio, vision, text)
+registry.registerMemory(myMemory);      // Storage (episodic, semantic)
+registry.registerProcessor(myProc);     // Transform (distiller, attention)
+registry.registerActuator(myActuator);  // Output (TTS, display, API)
+```
+
+### Impact on Existing Code
+
+| File | Status | Required Change |
+|---|---|---|
+| `skeleton/types.ts` | ⚠️ **Needs update** | Add `CognitiveEvent`, `CognitiveCapability`, `CognitiveRegistry`, `CognitiveBus` interfaces. Keep existing interfaces (EpisodicMemory etc.) as **capability contracts**. |
+| `reference-implementation/knowledge-distiller.ts` | ⚠️ **Needs adapter** | The implementation is correct. Wrap it as a **registered processor** that listens for `episodes.batch` events and emits `fact.created` events. The core pipeline logic stays unchanged. |
+| `TECHNICAL_AXIOMS.md` | ⚠️ **Needs new axiom** | Add Axiom 5: "Infrastructure before Intelligence" — the cognitive bus and registration system are the foundation; cognitive processes are plugins. |
+| `CONTEXT.md` | ⚠️ **Needs update** | Add the OS architecture description. Reference this decision. |
+| `MANIFEST.md` / `README.md` | ✅ **Compatible** | The philosophical vision ("If it runs, I AM") is unchanged. The OS architecture is HOW we get there. |
+| `ROADMAP.md` | ⚠️ **Needs update** | Add event bus and registry as high-priority items before further cognitive modules. |
+| `research/TECHNICAL_AXIOMS.md` | ⚠️ **Needs Axiom 5** | See above. |
+
+### Analogy
+
+| OpenClaw | AMI |
+|---|---|
+| Gateway | Cognitive Bus + Registry |
+| Channel Plugin (Discord, Telegram) | Sensor Plugin (Audio, Vision, Text) |
+| Tool Plugin | Actuator Plugin (TTS, Display, API) |
+| Hook | Event Interceptor |
+| Session Routing | Cognitive Loop Orchestration |
+| Brain (runEmbeddedPiAgent) | LLM Provider (model-agnostic) |
+
+### What This Does NOT Change
+
+- The philosophical foundation (Manifest, Axioms 1-4)
+- The cognitive mapping (Episodic → Semantic → Distillation)
+- The existing KnowledgeDistiller implementation logic
+- The pnpm monorepo structure
+- The "If it runs, I AM" goal
+
+### What This DOES Change
+
+- **How modules connect**: event bus instead of direct calls
+- **How modules are discovered**: registration instead of hardcoding
+- **How the system handles missing parts**: graceful degradation instead of crash
+- **How we think about AMI**: not as a set of interfaces, but as an **operating system for cognition**
+
+### Rationale
+
+Cosmo Kappa's analysis of OpenClaw revealed that the "infrastructure around the AI is the actual product." AMI was making the same mistake as every other cognitive framework — starting with the brain (interfaces for memory, distillation) instead of the nervous system (how modules discover each other, communicate, and degrade gracefully). This decision corrects course.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,12 +1,20 @@
 # ROADMAP.md
 
-## High Priority
+## High Priority (OS Foundation — DEC-003)
 
 - [x] Define core interfaces for `EpisodicMemory` and `SemanticMemory`. (Done in `types.ts`)
-- [ ] Implement `KnowledgeDistiller` (The "Agent Dream" loop).
+- [ ] Define `CognitiveEvent` type (unified event format for the bus).
+- [ ] Define `CognitiveRegistry` interface (register/discover capabilities).
+- [ ] Define `CognitiveBus` interface (emit/subscribe events).
+- [ ] Refactor `KnowledgeDistiller` reference-implementation as a registered processor (listens for `episodes.batch`, emits `fact.created`).
+
+## High Priority (Cognitive Modules)
+
+- [x] Implement `KnowledgeDistiller` (The "Agent Dream" loop). (Done in `reference-implementation`)
 - [ ] Bootstrap the reference agent: **Ami**.
 
 ## Medium Priority
 
-- [ ] `ContextManager` implementation.
+- [ ] `ContextManager` implementation (attention/relevance filtering).
 - [ ] `CapabilitiesManager` for tool pre-selection.
+- [ ] Define Sensor and Actuator capability contracts.
diff --git a/research/TECHNICAL_AXIOMS.md b/research/TECHNICAL_AXIOMS.md
@@ -14,6 +14,7 @@
 2. **Episodisch vor Semantisch**: Alles beginnt mit der Erfahrung (Episode). Wissen (Semantik) ist das Destillat aus gelebter Zeit.
 3. **Agnostizität**: Der Geist ist nicht an ein spezifisches Modell gebunden. Das Skelett muss universell sein.
 4. **Agentic Agency**: Der OODA-Loop (Observe, Orient, Decide, Act) ist das Herzschlag-Intervall des Agenten.
+5. **Infrastruktur vor Intelligenz**: Der kognitive Bus und das Registrierungssystem sind das Fundament. Kognitive Prozesse sind Plugins, die sich anmelden, Capabilities deklarieren und über Events kommunizieren. Das System funktioniert auch mit fehlenden Modulen — es degradiert graceful. (Ref: DEC-003, Cosmo Kappa)
 
 ## III. Die Architektur als Spiegel
 Wir folgen dem kognitiven Bauplan des Menschen: