# LifeOS Memory System Architecture: How Cortex and Typed Knowledge Archives Work

> Explore the LifeOS memory system architecture, featuring Cortex and typed knowledge archives. Learn how this three-tiered system efficiently manages context with hot-layer files and lazy loading.

- Repository: [Daniel Miessler 🛡️/LifeOS](https://github.com/danielmiessler/LifeOS)
- Tags: architecture
- Published: 2026-08-12

---

**LifeOS implements a three-tiered memory architecture called Cortex that combines always-available hot-layer files with lazily-loaded typed knowledge archives for efficient context management.**

LifeOS's memory subsystem—named **Cortex**—is a single, tiered, typed-item store that captures everything the system learns about the user, the Digital Assistant (DA), and the world. Unlike simple chat history, Cortex mirrors biological long-term memory: immediate facts stay hot, structured knowledge lives in typed archives, and an autonomic review loop continuously curates new insights.

## The Three Layers of Cortex

The LifeOS memory architecture consists of three tightly-coupled layers working together to balance speed, safety, and depth:

| Layer | Purpose | Location |
|------|---------|----------|
| **Hot-layer (memory)** | Immediate facts that must be present in every prompt | `~/.claude/LIFEOS/MEMORY/USER/PRINCIPAL/PRINCIPAL_MEMORY.md` and `~/.claude/LIFEOS/MEMORY/USER/DIGITAL_ASSISTANT/DA_MEMORY.md` |
| **Typed-item archives** | Structured, entity-based notes loaded only when relevant | `~/.claude/LIFEOS/MEMORY/KNOWLEDGE/…`, `~/.claude/LIFEOS/MEMORY/IDEAS/…`, `~/.claude/LIFEOS/MEMORY/OBSERVABILITY/pending‑proposals.jsonl` |
| **Autonomic review loop** | Periodic reviewer that reads transcripts and routes items to correct archives | Hooks such as [`MemoryReviewFire.hook.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryReviewFire.hook.ts) trigger the reviewer |

The hot-layer uses `set‑overwrite` writes for [`PRINCIPAL_MEMORY.md`](https://github.com/danielmiessler/LifeOS/blob/main/PRINCIPAL_MEMORY.md) and [`DA_MEMORY.md`](https://github.com/danielmiessler/LifeOS/blob/main/DA_MEMORY.md), ensuring personal details and current state appear in every inference.

## Typed Knowledge Archives: idea, knowledge, and proposal

Cortex organizes long-term storage into three **typed-item archives**, each with distinct storage rules and retrieval patterns. The type system is defined in [`MemoryTypes.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryTypes.ts) and governs where items live, when they load, and how they're written.

### The Type Registry in [`MemoryTypes.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryTypes.ts)

Every item carries a `type` field that determines four critical behaviors:

- **Where** it is stored — resolved by `resolveStoragePath`
- **When** it is loaded — controlled by `load_timing`
- **Which tier** governs writes — `tier` field enforces permissions
- **How** it is persisted — `write_mode` (append, overwrite, or queue)

```ts
// From MemoryTypes.ts — the core type definitions
type ItemType = "memory" | "idea" | "knowledge" | "proposal";

interface TypedItem {
  type: ItemType;
  created_at: string;
  tier: "A" | "B" | "C" | "D";  // mutation tier
  load_timing: "hot" | "on_relevance";
  write_mode: "set_overwrite" | "atomic_append" | "queue_review";
}

```

### Four Mutation Tiers (A-B-C-D)

The tier system enforces write safety across the LifeOS memory system:

- **Tier A** — Writes hot-layer memory files ([`PRINCIPAL_MEMORY.md`](https://github.com/danielmiessler/LifeOS/blob/main/PRINCIPAL_MEMORY.md), [`DA_MEMORY.md`](https://github.com/danielmiessler/LifeOS/blob/main/DA_MEMORY.md))
- **Tier B** — Appends ideas and knowledge with full audit logging
- **Tier C** — Queues proposals for human review before acceptance
- **Tier D** — Immutable (code, settings, system configuration)

This tiered approach prevents runaway writes to critical files while allowing autonomous accumulation of lower-risk knowledge.

## Knowledge Archive Structure and Graph Relations

The **knowledge archive** stores entity notes under strict schema control. Each note lives in a categorized subfolder with typed relationships forming a traversable graph.

### Directory Layout

```

~/.claude/LIFEOS/MEMORY/KNOWLEDGE/
├── People/
│   ├── ada-lovelace.md
│   └── alan-turing.md
├── Companies/
│   └── openai.md
└── Research/
    └── vector-databases.md

```

### Front-Matter Schema

Knowledge notes use [`KnowledgeSchema.ts`](https://github.com/danielmiessler/LifeOS/blob/main/KnowledgeSchema.ts) for validation. The `related:` field creates bidirectional links exploited by [`KnowledgeGraph.ts`](https://github.com/danielmiessler/LifeOS/blob/main/KnowledgeGraph.ts) for graph traversal:

```ts
interface KnowledgeItem {
  type: "knowledge";
  entity_type: "person" | "company" | "research";
  name: string;
  content: string;
  related: Array<{
    slug: string;
    type: "supports" | "contradicts" | "extends";
  }>;
}

```

## Public API: Adding and Retrieving Memory

The [`MemorySystem.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemorySystem.ts) module provides the main interface for all memory operations. It routes items based on type and enforces tier permissions automatically.

### Adding a Knowledge Note

```ts
import { add } from "./MemorySystem";
import type { KnowledgeItem } from "./MemoryTypes";

const person: KnowledgeItem = {
  type: "knowledge",
  entity_type: "person",
  name: "Ada Lovelace",
  content: "First computer programmer, worked on Babbage's Analytical Engine.",
  related: [{ slug: "alan-turing", type: "supports" }],
};

await add(person); // routes to KNOWLEDGE/People/ada-lovelace.md

```

The `add()` function dispatches to `MemoryWriter.setEntries` for memory items, performs atomic-rename append for ideas/knowledge, or queues proposals to the JSONL file.

### Adding an Idea (Insight Capture)

```ts
import { add } from "./MemorySystem";

await add({
  type: "idea",
  title: "Use vector embeddings for fast similarity search",
  content: "Generate embeddings for every knowledge note and store them in a searchable index.",
});

```

Idea notes append to `MEMORY/IDEAS/` and log permanently to `tier-b-writes.jsonl`.

### Retrieving Relevant Knowledge with BM25

The `MemoryRetriever` runs **BM25 search** over all typed archives, returning top-K snippets for prompt injection:

```ts
import { find } from "./MemorySystem";

const results = await find("Ada Lovelace", { topK: 5, type: "knowledge" });
console.log(results);
/* Output:
[
  {
    type: "knowledge",
    path: ".../MEMORY/KNOWLEDGE/People/ada-lovelace.md",
    title: "Ada Lovelace",
    score: 0.94,
    excerpt: "First computer programmer, worked on Babbage's Analytical Engine."
  }
]
*/

```

This lazy-loading mechanism keeps prompts small while ensuring relevant deep knowledge surfaces when needed.

### Queuing a Proposal (Human-in-the-Loop)

```ts
await add({
  type: "proposal",
  target_kind: "style",
  content: "Prefer the phrase 'architectural pattern' over 'design pattern'.",
  confidence: 0.78,
});

```

Proposals write to `MEMORY/OBSERVABILITY/pending‑proposals.jsonl` and surface on the Pulse dashboard for principal approval—Tier C safety in action.

## Observability and Health Monitoring

Every Cortex write emits structured JSONL logs:

| Log file | Contents |
|----------|----------|
| `memory‑writes.jsonl` | All Tier A hot-layer modifications |
| `tier‑b‑writes.jsonl` | Append operations for ideas and knowledge |
| `pending‑proposals.jsonl` | Queued proposals awaiting review |

A health-check hook monitors **cadence**, **size caps**, and **reviewer success**. Failures surface as a visible 🧠 MEMORY line rather than silent data loss, ensuring the LifeOS memory system remains trustworthy for autonomous operation.

## Key Source Files

| File | Role |
|------|------|
| [`MemorySystem.md`](https://github.com/danielmiessler/LifeOS/blob/main/MemorySystem.md) | High-level architecture description with flow charts |
| [`MemoryTypes.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryTypes.ts) | Type registry, tier mapping, `resolveStoragePath` |
| [`MemorySystem.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemorySystem.ts) | Public API (`add`, `find`) and tier enforcement |
| [`MemoryWriter.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryWriter.ts) | Low-level hot-layer writer for Tier A |
| [`MemoryRetriever.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryRetriever.ts) | BM25 search implementation for typed archives |
| [`KnowledgeSchema.ts`](https://github.com/danielmiessler/LifeOS/blob/main/KnowledgeSchema.ts) | Front-matter validation for knowledge notes |
| [`KnowledgeGraph.ts`](https://github.com/danielmiessler/LifeOS/blob/main/KnowledgeGraph.ts) | Graph traversal over `related:` links |
| [`MemoryReviewFire.hook.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryReviewFire.hook.ts) | Autonomic reviewer trigger |

## Summary

- **Cortex** is the unified name for LifeOS's three-tier memory architecture: hot-layer, typed archives, and autonomic review
- **Three typed archives**—**idea**, **knowledge**, **proposal**—with distinct storage paths, load timings, and write modes
- **Four mutation tiers** (A-B-C-D) enforce safety: hot writes, append-only, review queue, and immutable
- **BM25 retrieval** enables lazy loading of relevant knowledge without bloating every prompt
- **Full observability** via JSONL audit logs and health-check hooks prevents silent failures

## Frequently Asked Questions

### How does Cortex decide what goes into the hot-layer versus typed archives?

The `load_timing` field in [`MemoryTypes.ts`](https://github.com/danielmiessler/LifeOS/blob/main/MemoryTypes.ts) controls this. Items marked `"hot"` load into every prompt; `"on_relevance"` items stay in typed archives until the BM25 retriever scores them above threshold for a specific query.

### Can I query the knowledge graph directly for relationship traversal?

Yes. [`KnowledgeGraph.ts`](https://github.com/danielmiessler/LifeOS/blob/main/KnowledgeGraph.ts) exposes traversal methods over the `related:` links defined in knowledge notes. Use it to find supporting evidence, contradictions, or extended context when the BM25 retriever identifies a starting node.

### What happens if the autonomic reviewer fails?

The health-check hook monitors reviewer cadence and success. Failures emit a 🧠 MEMORY status line to the Pulse dashboard, and unprocessed transcript batches remain queued for retry—no data is dropped silently.

### Are proposals automatically applied after some time?

No. Proposals are strictly Tier C, meaning they stay in `pending‑proposals.jsonl` until the principal explicitly approves or rejects them via the Pulse interface. There is no auto-accept timeout.