3-Tier Memory Architecture

OrchestKit maintains a 3-tier memory architecture that stores decisions once and surfaces them automatically in every future session. Each tier serves a distinct purpose, and the system degrades gracefully: if a tier is unavailable, the tiers above it continue operating without interruption.

Architecture at a Glance

How Decisions Flow Across Tiers

When you store a decision -- whether explicitly via /ork:remember or implicitly through the capture hooks -- the memory writer routes it to all configured backends simultaneously.

/ork:remember "Use cursor-based pagination for all list endpoints"
    |
    +---> Tier 1: Graph Memory
    |     mcp__memory__create_entities + create_relations
    |     Stores entities: cursor-pagination (Pattern), list-endpoints (Component)
    |     Stores relation: project -> CHOSE -> cursor-pagination
    |
    +---> Tier 2: Local Persistence
    |     Appends to .claude/memory/decisions.jsonl
    |     Queues graph ops to .claude/memory/graph-queue.jsonl
    |
    +---> Tier 3: CC Native (only if confidence >= 0.7)
          Writes to ~/.claude/projects/<project>/memory/MEMORY.md
          Claude auto-injects this into every future system prompt

The Confidence Threshold

Not every decision reaches Tier 3. Only decisions with a confidence score of 0.7 or higher are promoted to CC Native MEMORY.md. This keeps Claude's system prompt concise and focused on high-signal decisions. The confidence score is calculated from:

• Explicit user statements ("we decided...", "always use...") score higher
• Decisions with rationale ("because...") score higher than bare facts
• Preferences stated directly by the user score higher than inferred patterns

Lower-confidence observations still persist in Tier 1 (Graph) and Tier 2 (Local), where they are available through explicit search.

The Read Path

When Claude processes your prompt, multiple hooks activate to surface relevant memory.

On Every Prompt

The memory-context hook (prompt lifecycle) fires on every prompt submission. It:

1. Scans your prompt for trigger keywords (implement, create, refactor, previous, decision, pattern, etc.)
2. Extracts meaningful search terms by removing stopwords
3. Injects a system message telling Claude to search the knowledge graph with those terms
4. If the prompt contains relationship keywords (related, connected, depends on), adds graph traversal hints

This is why Claude "remembers" your past decisions without you asking. The hook silently provides relevant context before Claude generates a response.

On First Prompt of a Session

The memory-context-loader hook (prompt lifecycle, once: true) fires exactly once per session. It:

1. Reads the last 10 decisions from .claude/memory/decisions.jsonl
2. Formats them as a markdown context block with type labels, rationale, and entity tags
3. Injects them into Claude's context as "Recent Project Decisions"
4. Caps output at 3000 characters to stay within budget

This ensures Claude always starts a session with your most recent decisions loaded, even before you type a prompt related to them.

On Agent Spawn

When a subagent is created, the graph-memory-inject hook fires -- it searches the knowledge graph for entities related to the agent's domain (e.g., a database-engineer agent gets entities tagged with PostgreSQL, schema, migration).

The Write Path

Decisions enter the system through multiple channels.

Explicit Storage

# Basic decision
/ork:remember "Use JWT tokens for auth, not session cookies"

# Successful pattern
/ork:remember --success "Cursor-based pagination scales for 2M+ rows"

# Anti-pattern
/ork:remember --failed "Offset pagination caused timeouts at 1M rows"

# Cross-project best practice
/ork:remember --global "Always validate input at API boundaries"

Automatic Capture

OrchestKit captures decisions automatically through hooks:

Entity and Relation Extraction

The memory writer automatically extracts structured data from natural language:

Memory Fabric: Unified Search

The Memory Fabric layer sits above individual tiers and provides unified search with cross-referencing. When you run /ork:memory search "pagination", the fabric:

1. Parses the query into search terms and entity hints
2. Dispatches queries to the knowledge graph
3. Normalizes results to a common format with source, relevance score, and entities
4. Deduplicates results with greater than 85% text similarity, keeping the higher-relevance copy
5. Ranks by: recency (0.3) x relevance (0.5) x source_authority (0.2)

Memory Health

Check the health of all tiers at any time:

/ork:memory status

The health check validates:

• Graph tier: .claude/memory/ exists, decisions.jsonl is parseable, queue depth is below threshold
• Local tier: JSONL files are parseable, queue depths are below threshold
• CC Native tier: MEMORY.md exists and is readable

Possible statuses: healthy, degraded (corrupt lines or high queue depth), unavailable (missing directory or API key).

Sharing Scopes

Decisions are scoped to control where they are visible:

Decisions with confidence >= 0.8, a rationale, and a well-known technology or pattern keyword are automatically marked as generalizable and eligible for global sharing.

Graceful Degradation

The system is designed to function at every level of configuration:

Next Steps

• Graph Memory -- how the primary knowledge graph works
• Local Persistence -- JSONL queues and session backup
• CC Native Memory -- auto-promotion to MEMORY.md
• Set Up Cross-Session Memory -- hands-on cookbook