---
title: "Set Up Cross-Session Memory"
description: "Persist decisions, patterns, and context across conversations."
canonical: "https://orchestkit.yonyon.ai/docs/cookbook/setup-memory"
---

# Set Up Cross-Session Memory

Persist decisions, patterns, and context across conversations.

import { Callout } from 'fumadocs-ui/components/callout';

## Scenario

You have been working on a project for a week. Over that time you made twenty-plus architecture decisions: JWT over session cookies, PostgreSQL with pgvector for embeddings, cursor-based pagination for all list endpoints, Zod for runtime validation at API boundaries.

Then Monday arrives. You open a new Claude Code session. Claude knows none of it. It suggests session cookies. It reaches for offset pagination. Every conversation starts from zero.

OrchestKit solves this with a **3-tier memory architecture**: graph MCP for searchable entities, optional local JSONL artifacts, and Claude Code native MEMORY.md for durable session-start context. Graph recall is on demand (`/ork:memory` or MCP tools). MEMORY.md is loaded by Claude Code when present. Session-end hooks only suggest capture; they do not auto-write MEMORY.md.

## What You'll Use

| Component | Type | Purpose |
|---|---|---|
| `/ork:remember` | Command skill | Store decisions, patterns, and context in the knowledge graph (and optionally filesystem memory) |
| `/ork:memory` | Command skill | Search, load, sync, visualize stored knowledge |
| `session-summary` | Hook (stop, async) | After each assistant turn (when busy enough), suggests a graph entity capture and nudges `/ork:remember`; async output may arrive on a later turn |
| `memory-validator` | Hook (pretool) | Validates `mcp__memory__*` tool calls before they run |
| `mcp__memory__*` | MCP server | Graph database for entities and relations |

## The 3 Memory Tiers

Before diving into commands, understand what each tier does and when it activates.

| Tier | Storage | Config | Behavior |
|---|---|---|---|
| **1. Graph** | MCP `mcp__memory__*` | None (zero-config) | Stores entities with typed relations. Primary tier. Always available. |
| **2. Local** | `.claude/memory/*.jsonl` | None (auto-created) | Session artifacts and offline backup surfaces used by skills and compaction snapshots. |
| **3. CC Native** | `~/.claude/projects/*/memory/MEMORY.md` | None | Loaded by Claude Code at session start. Survives plugin removal. Written by skills/agents, not by a dedicated OrchestKit writer hook. |

<Callout type="info">
Graph and MCP memory require zero configuration once the memory MCP server is available. Local JSONL files appear when something writes them. CC Native MEMORY.md is maintained by Claude Code and by explicit skill or agent edits (for example `/ork:remember` filesystem updates). There is no OrchestKit hook that auto-promotes decisions into MEMORY.md.
</Callout>

## Step-by-Step

### Step 1: Store Your First Decision

Use `/ork:remember` to record an architecture decision. The skill auto-detects the category from keywords in your text, extracts entities, and creates typed relations in the knowledge graph.

```bash
/ork:remember "We use JWT tokens for auth, not session cookies"
```

**What you see:**

```
Remembered (authentication): "We use JWT tokens for auth, not session cookies"
   -> Stored in knowledge graph
   -> Created entity: JWT (Technology)
   -> Created entity: session-cookies (Technology)
   -> Created relation: project -> CHOSE_OVER -> JWT vs session-cookies
   Graph: 3 entities, 1 relation
```

The skill detected `authentication` as the category from the keywords "JWT" and "auth". It extracted two Technology entities and a `CHOSE_OVER` relation. All of this happens in a single command with no manual tagging.

### Step 2: Store Patterns with Outcome Tracking

Mark successful patterns so OrchestKit reinforces them in future sessions. Mark anti-patterns so it warns you away from repeating mistakes.

```bash
# A pattern that worked well
/ork:remember --success "Cursor-based pagination scales well for our 2M-row tables"

# A pattern that caused problems
/ork:remember --failed "Offset pagination caused timeouts on tables with 1M+ rows"
```

**Success output:**

```
Remembered SUCCESS (pagination): "Cursor-based pagination scales well for our 2M-row tables"
   -> Stored in knowledge graph
   -> Created entity: cursor-pagination (Pattern)
   Graph: 1 entity, 0 relations
```

**Anti-pattern output:**

```
Remembered ANTI-PATTERN (pagination): "Offset pagination caused timeouts on tables with 1M+ rows"
   -> Stored in knowledge graph
   -> Created entity: offset-pagination (AntiPattern)
   Lesson: Use cursor-based pagination for large datasets
```

The `--failed` flag creates an `AntiPattern` entity type instead of `Pattern`. When a future session mentions offset pagination, OrchestKit surfaces the anti-pattern warning automatically.

<Callout type="warn">
If you provide both `--success` and `--failed` on the same command, OrchestKit asks you to clarify. A single decision cannot be both a success and a failure.
</Callout>

### Step 3: Search Across All Tiers

Query stored knowledge from any future session using `/ork:memory search`:

```bash
/ork:memory search "authentication"
```

**What you see:**

```
Found 3 results matching "authentication":

[GRAPH] JWT (Technology)
   -> CHOSE_OVER -> session-cookies
   Observations: "Used for auth, not session cookies"

[GRAPH] auth-service (Component)
   -> USES -> JWT
   Observations: "Handles login, signup, token refresh"

[GRAPH] oauth-provider (Technology)
   -> USED_FOR -> third-party auth
```

Results show the source tier, entity type, relations, and observations. You can filter and scope results with flags:

```bash
# Filter by category
/ork:memory search --category database "indexing strategy"

# Scope to a specific agent's memories
/ork:memory search --agent backend-system-architect "caching"

# Search cross-project best practices
/ork:memory search --global "rate limiting"
```

### Step 4: Verify Memory System Health

Check that all tiers are operational at any time:

```bash
/ork:memory status
```

**What you see:**

```
Memory System Status:
  Graph Memory:  healthy (42 decisions, 0 corrupt)
  Queue Depth:   3 pending
  CC Native:     active (MEMORY.md present)
```

### Step 5: Visualize Your Knowledge Graph

See how your decisions connect to each other:

```bash
/ork:memory viz
```

This produces a Mermaid diagram showing entities and relations:

```
graph LR
  JWT[JWT] -->|CHOSE_OVER| session-cookies[session-cookies]
  auth-service[auth-service] -->|USES| JWT
  PostgreSQL[PostgreSQL] -->|USES| connection-pooling[connection-pooling]
  PostgreSQL -->|USES| pgvector[pgvector]
  pgvector -->|USED_FOR| RAG[RAG]
  cursor-pagination[cursor-pagination] -->|CHOSE_OVER| offset-pagination[offset-pagination]
```

Focus on a specific entity or limit relationship depth:

```bash
# Focus on one entity and its neighbors
/ork:memory viz --entity PostgreSQL --depth 2

# Filter to a specific entity type
/ork:memory viz --type Technology
```

## Behind the Scenes

Here is what OrchestKit actually wires for memory today (verified against `src/hooks/hooks.json` and the registered entry maps).

### On Session Start

`lifecycle/sync-session-dispatcher` materializes profile and antipattern rules into `.claude/rules/`. Claude Code itself loads project `MEMORY.md` at session start. There is no OrchestKit UserPromptSubmit hook that injects recent JSONL decisions on every prompt.

### On MCP Memory Calls

`pretool/mcp/memory-validator` runs on `mcp__memory__*` PreToolUse. It denies oversized entity (and observation) payloads, warns on missing required fields, and only logs unknown entity types (no warning result). Relation creates check required fields only; there is no relation size check.

### On Stop (after every assistant turn)

`stop/session-summary` and `stop/handoff-writer` are async Stop hooks. Claude Code fires Stop after every assistant turn, not only when you quit. Their output is delivered asynchronously and may land on a later turn. If you end the session right after a qualifying turn, the suggestion may never reach Claude; if you continue, the nudge can recur.

When the session has had meaningful work (20 or more tool calls), `session-summary` returns an `additionalContext` suggestion to create a session graph entity, and for high-activity sessions (over 50 tool calls) it nudges you to run `/ork:remember`. It does not write local JSONL or MEMORY.md itself.

`handoff-writer` may include recent entries from `.claude/logs/decisions.jsonl` in the handoff note when that file exists.

### Before Compaction

`lifecycle/pre-compact-saver` snapshots local `.claude/memory/*.jsonl` entry counts and recent `.claude/logs/decisions.jsonl` lines into session state for diagnostics. Post-compact recovery does not reinject that snapshot into the model. The saver does not promote decisions into MEMORY.md.

### The Write Path

When you invoke `/ork:remember`, the skill's primary path is the knowledge graph. Filesystem MEMORY.md updates are agent-side Edit/Write operations when you choose durable auto-memory scope, not a background hook:

| Tier | Storage | Method |
|---|---|---|
| **1. Graph** | Knowledge graph | `mcp__memory__create_entities` + `create_relations` |
| **2. Local** | `.claude/memory/` artifacts | Written by skills/scripts when used; not auto-flushed by a writer hook |
| **3. CC Native** | `MEMORY.md` | Claude Code loads it at session start; skills/agents edit it explicitly when asked |

### Entity and Relation Extraction

The skill automatically extracts entities from your text using these heuristics:

- **Capitalized terms** become Technology entities (PostgreSQL, React, FastAPI)
- **Agent names** with hyphens become Agent entities (database-engineer, backend-system-architect)
- **Pattern names** become Pattern entities (cursor-pagination, connection-pooling)
- **Relationship phrases** like "uses", "requires", "prefers", "chose X over Y" become typed relations (USES, REQUIRES, PREFERS, CHOSE_OVER)
- **Failed patterns** become AntiPattern entities with an extracted lesson

Graph memory stores explicit relationships between entities: `"JWT" -> USED_FOR -> "auth-service"`. This structure enables precise queries like "what does auth-service use?", something flat text search cannot do.

## Tips

<Callout type="info">
**Store investigation context explicitly.** Run `/ork:remember "Session summary: completed X, found Y, next steps Z"` when you want durable recall. `session-summary` only suggests graph capture via additionalContext on Stop turns (async, after each assistant turn when busy enough); it does not persist MEMORY.md for you.
</Callout>

<Callout type="info">
**Use categories to organize decisions.** The 12 built-in categories (decision, architecture, pattern, blocker, constraint, preference, pagination, database, authentication, api, frontend, performance) make searching significantly faster. Use `--category` on both `remember` and `search` commands for precision.
</Callout>

<Callout type="info">
**Use `--global` for cross-project wisdom.** Decisions like "always validate input at API boundaries" apply everywhere. Store them with `/ork:remember --global` and search them with `/ork:memory search --global`. They use a separate user ID (`orchestkit-global-best-practices`) so they never pollute project-specific context.
</Callout>

<Callout type="warn">
**Duplicate detection is automatic.** If you store the same decision twice, OrchestKit detects the existing entity in the graph and adds a new observation instead of creating a duplicate. You see: "Updated existing entity (added observation)".
</Callout>

<Callout type="info">
**Resume sessions with memory load.** Start a new session with `/ork:memory load` to pull in recent decisions, active project context, and agent-specific memories. Pair this with Claude Code's `--from-pr` flag for PR work: `claude --from-pr 123` loads the PR context, then `/ork:memory load` layers in your architecture decisions on top.
</Callout>

<Callout type="info">
**Load memory explicitly when you need it.** There is no per-prompt OrchestKit injector that ranks and injects graph decisions automatically. Use `/ork:memory load` or `/ork:memory search` (or MCP `search_nodes`) to pull relevant context. Keep MEMORY.md concise so Claude Code session-start loading stays useful.
</Callout>

## Next Steps

- **[Memory Overview](/docs/memory/overview)**: Deep dive into the 3-tier architecture
- **[Configuration](/docs/getting-started/configuration)**: Set up environment variables
- **[Security Audit Cookbook](/docs/cookbook/security-audit)**: See memory in action during a security review