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

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 trigger the reviewer

The hot-layer uses set‑overwrite writes for PRINCIPAL_MEMORY.md and 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 and governs where items live, when they load, and how they're written.

The Type Registry in 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)

// 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, 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 for validation. The related: field creates bidirectional links exploited by KnowledgeGraph.ts for graph traversal:

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 module provides the main interface for all memory operations. It routes items based on type and enforces tier permissions automatically.

Adding a Knowledge Note

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)

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:

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)

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	High-level architecture description with flow charts
MemoryTypes.ts	Type registry, tier mapping, resolveStoragePath
MemorySystem.ts	Public API (add, find) and tier enforcement
MemoryWriter.ts	Low-level hot-layer writer for Tier A
MemoryRetriever.ts	BM25 search implementation for typed archives
KnowledgeSchema.ts	Front-matter validation for knowledge notes
KnowledgeGraph.ts	Graph traversal over related: links
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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}