---
title: "Memory Bridge and Context Injection"
description: "How OrchestKit validates graph memory writes, suggests capture on async Stop turns, and guards MEMORY.md size, without a dedicated auto-writer hook."
canonical: "https://orchestkit.yonyon.ai/docs/hooks/memory-hooks"
---

# Memory Bridge and Context Injection

How OrchestKit validates graph memory writes, suggests capture on async Stop turns, and guards MEMORY.md size, without a dedicated auto-writer hook.

import { Callout } from "fumadocs-ui/components/callout";
import { Steps, Step } from "fumadocs-ui/components/steps";

## The Memory Pipeline

OrchestKit no longer ships a `memory-writer` hook (or per-prompt `memory-context` / `memory-context-loader` injectors). Memory persistence is skill-driven (graph MCP plus optional filesystem MEMORY.md edits). A small set of hooks still touch the pipeline:

```
Session start                         During session                      Stop (every assistant turn, async)
-------------                         --------------                      --------------------------------
CC loads MEMORY.md                    /ork:remember -> mcp__memory__*     stop/session-summary
sync-session-dispatcher               memory-validator (PreToolUse)       (graph entity suggestion; may
  materializes profile rules          sync-write-edit-dispatcher           land on a later turn)
                                      (context-file-budget-guard on       stop/handoff-writer
                                       MEMORY.md / CLAUDE.md writes)      (may cite decisions.jsonl)

                                                                          PreCompact:
                                                                          pre-compact-saver snapshots
                                                                          .claude/memory + logs
```

## Memory Validator (MCP PreToolUse)

**Hook:** `pretool/mcp/memory-validator`
**Event:** PreToolUse (`mcp__memory__*`)
**Purpose:** Validate knowledge graph operations before they execute.

Wired in `hooks.json` and `entries/pretool.ts`. Entity creates get size limits (deny on oversized names/observations) plus required-field checks. Relation creates get required-field checks only (no relation size limit). Missing required fields return `outputWarning` and still allow the call. Unknown entity types are logged only (no warning result) and still allow the call.

## Session Summary (Stop)

**Hook:** `stop/session-summary`
**Event:** Stop (`async: true` in `hooks.json`)
**Purpose:** Suggest graph entity capture after assistant turns that clear the activity threshold.

This is the graph-first replacement for older local-capture hooks. It does not write JSONL or MEMORY.md. Because Stop fires after every assistant turn and this hook is async, the suggestion is delivered on a later turn (or may be lost if the session ends immediately).

### How It Works

1. Checks whether the session had meaningful work (20 or more tool calls). If not, it exits silently.
2. Builds a session entity name from the date and branch (for example `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 (more than 50 tool calls), nudges the user to run `/ork:remember`.

```typescript
// 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}`,
  },
};
```

## Handoff Writer (Stop)

**Hook:** `stop/handoff-writer`
**Event:** Stop (`async: true` in `hooks.json`)

Runs after every assistant turn (async). Reads recent lines from `.claude/logs/decisions.jsonl` (when present) to enrich the handoff note. That log path is separate from `.claude/memory/decisions.jsonl` used by some skill scripts.

## PreCompact Saver

**Hook:** `lifecycle/pre-compact-saver`
**Event:** PreCompact

Snapshots local `.claude/memory/*.jsonl` entry counts and recent `.claude/logs/decisions.jsonl` content into session state for post-compaction recovery. Despite older comments in the source header, this hook does not write CC native MEMORY.md.

## MEMORY.md Budget Guard

**Hook:** `context-file-budget-guard` (via `pretool/write-edit/sync-write-edit-dispatcher`)
**Event:** PreToolUse (Write / Edit)

Advises when a Write or Edit would push `MEMORY.md` (or `CLAUDE.md`) past its soft size budget. Claude Code still injects MEMORY.md at session start; OrchestKit only warns on oversized edits. There is no OrchestKit hook that auto-appends decisions into MEMORY.md.

## What Was Removed

These names still appear in older docs or illustrative transcripts. They are not registered hooks on main:

| Former name | Status |
|-------------|--------|
| `memory-writer` / `memory-writer.ts` | Removed. No file, no registry entry. |
| `memory-context` / `memory-context-loader` | Removed from UserPromptSubmit. Comments still mention a move to SessionStart, but `materializeDecisionRules()` is not implemented. |
| `auto-remember-continuity` | Removed from Stop. |
| `graph-queue-sync` | Removed with the mem0/cloud memory cut. |
| `memory-fabric-init` | Removed. |

## Storage Surfaces (Public Model)

Docs still describe three storage surfaces. `checkMemoryHealth()` in `lib/memory-health.ts` currently only checks whether `.claude/memory/` exists. Claude Code loads MEMORY.md at session start when the file is present:

| Surface | Storage | Written By | Read By |
|---------|---------|-----------|---------|
| **Knowledge Graph** | MCP `mcp__memory__*` | `/ork:remember` (and agent MCP calls), validated by `memory-validator` | `/ork:memory search`, agent tool use |
| **Local JSONL** | `.claude/memory/*.jsonl` | Skills/scripts when used; snapshotted by `pre-compact-saver` | Skill status/viz scripts; compaction recovery |
| **CC Native** | `MEMORY.md` | Skills/agents via Edit/Write; guarded by `context-file-budget-guard` | Claude Code session-start load (automatic) |

<Callout type="info">
There is no OrchestKit posttool writer that auto-promotes high-confidence decisions into MEMORY.md. Use `/ork:remember` (graph) and explicit filesystem memory edits when you want durable native memory.
</Callout>

## Profile Rules (SessionStart)

Profile materialization runs inside `lifecycle/sync-session-dispatcher` at SessionStart (`materializeProfileRules()`). That is identity and conventions, not decision JSONL injection.

## Summary: Which Hooks Touch Memory?

| Hook | Event | Direction | Frequency |
|------|-------|-----------|-----------|
| `memory-validator` | PreToolUse (MCP) | Validate | Per `mcp__memory__*` call |
| `sync-write-edit-dispatcher` (`context-file-budget-guard`) | PreToolUse (Write/Edit) | Advise | Per MEMORY.md / CLAUDE.md write |
| `session-summary` | Stop (async) | Write hint (graph via additionalContext) | After each assistant turn when busy enough; delivery may be delayed |
| `handoff-writer` | Stop (async) | Read (`.claude/logs/decisions.jsonl`) | After each assistant turn (async) |
| `pre-compact-saver` | PreCompact | Snapshot (local + logs) | On compaction |
| `sync-session-dispatcher` | SessionStart | Materialize profile rules | Once per startup |