Memory Bridge and Context Injection

The Memory Pipeline

OrchestKit maintains memory across sessions through a pipeline of hooks that capture, store, load, and inject context. The system follows a graph-first architecture: the knowledge graph (via MCP) is always available with zero configuration.

Session N                                   Session N+1
---------                                   -----------
User prompt                                 SessionStart
    |                                           |
    v                                           v
memory-context  --->  search graph  --->  memory-context-loader
(every prompt)        for past decisions    (once, first prompt)
    |                                           |
    v                                           v
Stop (fire-and-forget)                    additionalContext injected
    |                                     into Claude's context
    +--> session-summary (graph entity suggestion via additionalContext)
    +--> auto-remember-continuity

Memory Context Loader (First Prompt)

Hook: prompt/memory-context-loader Event: UserPromptSubmit (once: true) Purpose: Load recent project decisions as context on the first prompt of every session.

This hook reads from .claude/memory/decisions.jsonl -- a file written by the memory system during previous sessions. Each line is a JSON record containing a decision or preference:

{
  "id": "dec_abc123",
  "type": "decision",
  "content": {
    "what": "Use cursor-based pagination for the orders API",
    "why": "Offset pagination causes timeouts on tables with 1M+ rows"
  },
  "entities": ["cursor-pagination", "orders-api"],
  "metadata": {
    "timestamp": "2026-01-15T10:30:00Z",
    "confidence": 0.85,
    "category": "api",
    "project": "myproject"
  }
}

The hook loads the last 10 decisions, formats them as markdown, and injects them via additionalContext:

## Recent Project Decisions

- **[Decision]** Use cursor-based pagination for the orders API _(because: Offset pagination causes timeouts on tables with 1M+ rows)_ [cursor-pagination, orders-api]
- **[Preference]** Use Tailwind CSS for all new components [frontend, tailwind]
- **[Decision]** PostgreSQL 16 for the analytics database _(because: Need JSONB and vector support)_ [PostgreSQL, analytics]

_For deeper graph traversal: use mcp__memory__search_nodes or mcp__memory__open_nodes_

Budget Awareness

The context loader caps output at 3,000 characters to avoid consuming too much of the context window. If there are more decisions than fit within the budget, it truncates with a hint:

- _(additional decisions available via mcp__memory__search_nodes)_

Memory Context (Every Prompt)

Hook: prompt/memory-context Event: UserPromptSubmit (every prompt) Purpose: Search the knowledge graph for context relevant to the current prompt.

Unlike the context loader (which runs once and injects recent decisions), this hook runs on every prompt and performs keyword-based relevance detection.

Trigger Detection

The hook checks the prompt against two keyword lists:

Memory triggers (suggest memory search would be valuable): add, implement, create, build, design, refactor, update, modify, fix, change, continue, resume, remember, previous, last time, before, earlier, pattern, decision, how did we, what did we

Graph triggers (suggest relationship queries): relationship, related, connected, depends, uses, recommends, what does.*recommend, how does.*work with

How It Works

[Memory Context] For relevant past project decisions,
use mcp__memory__search_nodes with query="cursor pagination orders"

For relationships: mcp__memory__open_nodes on found entities
| Graph traversal available

Agent context: database-engineer

The hook does not execute the graph search itself -- it provides Claude with the instruction to do so. This keeps the hook fast (under 10ms) while giving Claude the information it needs to decide whether to query memory.

Global vs Project Scope

If the prompt starts with @global or mentions "cross-project" or "all projects", the hook switches to global scope:

[Memory Context] For relevant past cross-project decisions...

Session Summary (Stop)

Hook: stop/session-summary Event: Stop (fire-and-forget via background worker) Purpose: Suggest graph entity capture at session end for high-activity sessions.

This hook replaced the former capture-user-intent and memory-capture hooks as part of the graph-first memory architecture. Instead of writing local JSONL files during the session, it runs once at session end and suggests a graph entity via additionalContext.

How It Works

1. Checks whether the session had meaningful work (20+ tool calls). If not, it exits silently.
2. Builds a session entity name from the date and branch (e.g., Session-2026-03-06-feat/my-feature).
3. Classifies the session outcome from the last assistant message (question, summary, code, or unknown).
4. Constructs a mcp__memory__create_entities suggestion and returns it via additionalContext.
5. For high-activity sessions (50+ tool calls), nudges the user to run /ork:remember.

// The hook returns a graph entity suggestion, not a local file write
return {
  continue: true,
  suppressOutput: true,
  hookSpecificOutput: {
    additionalContext: `Session complete (${totalTools} tools, outcome=${outcome}).\nSuggested graph capture: ${graphSuggestion}`,
  },
};

This approach avoids local file I/O entirely -- CC's auto memory picks up the additionalContext and persists it to the knowledge graph.

Queue-Based Memory Sync

Memory writes are not performed immediately during the session. Instead, they are queued to local JSONL files and flushed at session end via the fire-and-forget stop hooks.

Graph Queue

File: .claude/memory/graph-queue.jsonl Flushed by: stop/graph-queue-sync

Each queued entry describes an entity or relation to create in the knowledge graph:

{
  "action": "create_entity",
  "entity": {
    "name": "PostgreSQL",
    "entityType": "Technology",
    "observations": ["Selected for analytics database", "Chosen for JSONB and vector support"]
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

{
  "action": "create_relation",
  "relation": {
    "from": "analytics-database",
    "to": "PostgreSQL",
    "relationType": "USES"
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

At session end, the graph-queue-sync hook reads the queue and executes the operations against the knowledge graph MCP.

Memory in Subagents

When a subagent is spawned, it inherits memory context from the parent session. Claude uses the agent's domain keywords (e.g., database, schema, migration for database-engineer) to search the knowledge graph via mcp__memory__search_nodes for relevant entities. This is handled natively by CC's skill matching -- no dedicated hook is needed.

Memory Fabric Initializer

Hook: pretool/mcp/memory-fabric-init Event: PreToolUse (mcp__memory__*) (once: true)

On the first MCP memory tool call of the session, this hook initializes the memory fabric -- setting up the connection to the knowledge graph. It runs once and silently.

Memory Validator

Hook: pretool/mcp/memory-validator Event: PreToolUse (mcp__memory__*)

Validates knowledge graph operations before they execute, ensuring entity names are properly formatted and relation types follow the expected vocabulary.

The Three-Tier Memory Architecture

OrchestKit's hooks bridge three storage tiers:

Auto-Remember Continuity

Hook: stop/auto-remember-continuity (fire-and-forget)

At session end, this hook reviews the session's key decisions and ensures they are stored for the next session. It acts as a safety net, catching any decisions that were not captured during the session's normal flow.

Profile Injector

Hook: prompt/profile-injector Event: UserPromptSubmit (once: true)

On the first prompt, this hook injects the user's profile context (project identity, team conventions, preferred tools) from .claude/context/identity.json. This is separate from memory -- it provides static configuration rather than learned decisions.

Summary: Which Hooks Touch Memory?