Graph Memory (Primary)

Graph memory is Tier 1 -- the primary storage layer in OrchestKit's memory architecture. It uses the @anthropic/memory-mcp-server to maintain a knowledge graph of entities and their relationships. It requires zero configuration and is always available.

How It Works

The knowledge graph stores two things:

1. Entities -- named nodes with a type and a list of observations
2. Relations -- directed, typed edges between entities

When you run /ork:remember "database-engineer uses pgvector for RAG applications", the system creates:

Entities:
  - database-engineer (Agent)     observations: ["Uses pgvector for RAG"]
  - pgvector (Technology)         observations: ["Used for RAG applications"]
  - RAG (Pattern)                 observations: ["Implemented with pgvector"]

Relations:
  database-engineer --USES--> pgvector
  pgvector --USED_FOR--> RAG

This structure enables precise queries that flat text search cannot answer: "What does database-engineer use?" returns pgvector via the USES relation. "What is pgvector used for?" returns RAG via the USED_FOR relation.

MCP Commands

All graph operations go through the MCP memory server. OrchestKit wraps these in hooks and skills so you rarely call them directly, but understanding the API helps when debugging or doing advanced queries.

Creating Entities

mcp__memory__create_entities
{
  "entities": [
    {
      "name": "cursor-pagination",
      "entityType": "Pattern",
      "observations": [
        "Chosen for all list endpoints",
        "Scales well for 2M+ row tables"
      ]
    },
    {
      "name": "PostgreSQL",
      "entityType": "Technology",
      "observations": [
        "Primary database for transactional data"
      ]
    }
  ]
}

Creating Relations

mcp__memory__create_relations
{
  "relations": [
    {
      "from": "project",
      "to": "cursor-pagination",
      "relationType": "CHOSE"
    },
    {
      "from": "cursor-pagination",
      "to": "offset-pagination",
      "relationType": "CHOSE_OVER"
    }
  ]
}

Searching the Graph

mcp__memory__search_nodes
{
  "query": "pagination database"
}

Returns matching entities with their observations and connected relations. This is the call the memory-context hook generates automatically on every prompt.

Opening Entity Details

mcp__memory__open_nodes
{
  "names": ["cursor-pagination", "PostgreSQL"]
}

Returns full entity details including all observations and all relations where the entity appears (as source or target).

Adding Observations

mcp__memory__add_observations
{
  "observations": [
    {
      "entityName": "cursor-pagination",
      "contents": ["Confirmed to handle 5M rows with sub-100ms response"]
    }
  ]
}

Appends new observations to an existing entity without creating duplicates. The /ork:remember skill uses this when it detects that an entity already exists in the graph.

Entity Types

The memory writer infers entity types from the content of your text:

Relation Types

Hooks That Read the Graph

Hooks That Write to the Graph

Agent Domain Mapping

When the graph-memory-inject hook fires for an agent spawn, it maps the agent type to domain keywords for targeted graph search:

This means a database-engineer agent automatically inherits all graph knowledge about PostgreSQL, schemas, and migrations stored in previous sessions.

User-Facing Commands

Storing Knowledge

# The /ork:remember skill writes to graph as primary
/ork:remember "Use PostgreSQL with pgvector for vector search"

Behind the scenes, the skill calls mcp__memory__create_entities and mcp__memory__create_relations to build the graph. It also writes to Tier 2 (local JSONL) as a backup.

Searching Knowledge

# The /ork:memory search skill queries the graph
/ork:memory search "database indexing strategy"

This calls mcp__memory__search_nodes and formats results showing entity types, observations, and relations.

Visualizing the Graph

# Render as Mermaid diagram
/ork:memory viz

# Focus on specific entity
/ork:memory viz --entity PostgreSQL --depth 2

# Filter by entity type
/ork:memory viz --type Technology

MCP Server Configuration

The knowledge graph MCP server is configured automatically by Claude Code. If you need to verify or troubleshoot the setup, the server configuration is:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropic/memory-mcp-server"]
    }
  }
}

Graph Size and Performance

The graph-memory-inject hook includes a safety check: if the graph data file is smaller than 100 bytes (approximately fewer than 3 entities), it skips injection to avoid noisy empty results. As you store more decisions, the graph grows richer and the injected context becomes more valuable.

The memory-context hook requires prompts to be at least 20 characters long before triggering a search. Single-word prompts or very short questions are skipped to avoid low-quality matches.

Next Steps

• Local Persistence -- how local JSONL files back up and queue graph operations
• Architecture Overview -- see how graph memory fits into the 3-tier system
• Set Up Cross-Session Memory -- hands-on walkthrough