Set Up Cross-Session Memory

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 that stores decisions once and surfaces them automatically in every future session. No manual copy-pasting. No re-explaining your stack. Decisions persist across conversations, projects, and machines.

What You'll Use

The 3 Memory Tiers

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

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.

/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.

# 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.

Step 3: Search Across All Tiers

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

/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:

# 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:

/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:

/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:

# 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 happens invisibly every time you interact with Claude in an OrchestKit session.

On Every Prompt Submit

The memory-context-injector hook fires on the prompt lifecycle event. It searches the knowledge graph for entities related to keywords in your prompt. If you type "set up the authentication endpoint," the hook finds your JWT decision and injects it into Claude's context -- before Claude even starts thinking about a response.

This is why Claude stops suggesting session cookies after you store the JWT decision. The hook silently provides the relevant context on every prompt.

On High-Confidence Decisions

The memory-writer hook monitors for decisions with confidence >= 0.7. When it detects one, it automatically writes to Tier 3 (CC Native MEMORY.md). This file lives at ~/.claude/projects/<your-project>/memory/MEMORY.md and is injected into Claude's system prompt for every session -- even sessions that do not use OrchestKit.

This means your most important decisions survive plugin removal, reinstallation, or upgrades. They are baked into Claude's base context.

On Session End

The auto-remember-continuity hook fires on the stop lifecycle event. It captures key decisions and context from the current session and persists them to the local queue (Tier 2), ensuring nothing is lost if the session ends unexpectedly or you forget to run /ork:remember manually.

The Write Path

When you invoke /ork:remember, the skill writes to all configured tiers simultaneously:

/ork:remember "JWT for auth"
    |
    +---> Tier 1: Graph (mcp__memory__create_entities + create_relations)
    +---> Tier 2: Local (.claude/memory/graph-queue.jsonl)
    +---> Tier 3: CC Native MEMORY.md (if confidence >= 0.7)

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

Next Steps

• Memory Overview -- Deep dive into the 3-tier architecture
• Configuration -- Set up environment variables
• Security Audit Cookbook -- See memory in action during a security review