Graphiti Memory

Graphiti Memory Skill

This skill teaches you how to use the Graphiti MCP for persistent knowledge graph memory. Graphiti provides semantic search across institutional knowledge, complementing the file-based memory system in docs/project_notes/.

Prerequisites

• Graphiti MCP tools available (search_nodes, search_memory_facts, add_memory, get_episodes)
• FalkorDB backend running with vector indexes configured

When to Search Graphiti (MANDATORY)

You MUST search Graphiti BEFORE attempting to solve problems.

How to Search

CRITICAL: Always Pass 2+ group_ids

There is a confirmed upstream bug where searching with a single group_ids parameter returns empty results. Always pass at least 2 group_ids.

# WRONG - Returns empty results (bug)
search_nodes(query="kubernetes", group_ids=["shakudo-platform-knowledge"])

# CORRECT - Add a dummy second group_id
search_nodes(query="kubernetes", group_ids=["shakudo-platform-knowledge", "dummy"])

The second group_id can be any string (even non-existent) - it just triggers the correct code path.

Search Tools

Search Examples

# Search for error-related knowledge
search_nodes(
    query="401 authentication error iOS Mattermost",
    group_ids=["shakudo-platform-knowledge", "dummy"],
    max_nodes=5
)

# Search for architectural decisions
search_nodes(
    query="database schema design patterns",
    group_ids=["shakudo-platform-knowledge", "dummy"],
    max_nodes=5
)

# Search for customer information
search_nodes(
    query="Acme Corp deployment requirements",
    group_ids=["shakudo-platform-knowledge", "dummy"],
    max_nodes=5
)

# Search for relationships/facts
search_memory_facts(
    query="keycloak authentication configuration",
    group_ids=["shakudo-platform-knowledge", "dummy"]
)

# List recent episodes
get_episodes(
    group_ids=["shakudo-platform-knowledge", "dummy"],
    max_episodes=10
)

Available Graphs

Default: Use shakudo-platform-knowledge for most queries unless working on a specific project.

When to Record Knowledge (MANDATORY)

You MUST record verified solutions to Graphiti after solving problems.

Record When ALL Conditions Met:

1. Problem was SOLVED (not just attempted)
2. Solution was VERIFIED working (tests pass, build succeeds, functionality confirmed)
3. Knowledge has reuse value (not a one-off typo fix)

What to Record

What NOT to Record

• Untested fixes ("this should work")
• Speculative solutions ("try X or maybe Y")
• One-off fixes (typo in one file)
• Duplicates (search first!)
• Sensitive credentials
• Temporary debugging details

How to Record

add_memory Tool

add_memory(
    name="Brief descriptive title",
    group_id="shakudo-platform-knowledge",  # Single group_id for writes
    episode_body="Detailed description with context, cause, solution, verification",
    source_description="Source of this knowledge (e.g., bugs.md, conversation)"
)

Recording Examples

Bug Fix

add_memory(
    name="Bug: iOS Mattermost 401 After OIDC Login",
    group_id="shakudo-platform-knowledge",
    episode_body="2026-01-26 Issue: iOS Mattermost app gets 401 Unauthorized after successful OIDC login. Root Cause: istio-ingress-jwt RequestAuthentication in istio-system validates JWT on all requests. iOS app sends Authorization header with Mattermost token, which fails Keycloak validation. Solution: kubectl delete requestauthentication istio-ingress-jwt -n istio-system. Verified: Yiran tested on test3, iOS login works.",
    source_description="bugs.md"
)

Architectural Decision

add_memory(
    name="Decision: Use Supabase Metaflow for App Databases",
    group_id="shakudo-platform-knowledge",
    episode_body="2026-01-29 Decision: All application development MUST use the Metaflow Supabase instance with dedicated schemas per application. Rationale: Prevents apps from accidentally modifying shared platform databases. Each app gets its own schema (e.g., ai_bdr_dialer). Connection: supabase-metaflow-postgresql.hyperplane-supabase-metaflow.svc.cluster.local:5432/postgres?schema={app_schema}. Alternative considered: Separate PostgreSQL instances (rejected - operational overhead).",
    source_description="decisions.md"
)

Customer Knowledge

add_memory(
    name="Customer: Acme Corp",
    group_id="shakudo-platform-knowledge",
    episode_body="Acme Corp is a Shakudo customer in the fintech industry. They use Shakudo for ML pipeline orchestration and model serving. Primary contact: John Smith (john@acmecorp.com). Deployed on GCP us-central1. Key requirements: SOC2 compliance, sub-100ms inference latency. Current usage: 50+ pipelines, 10 deployed models.",
    source_description="conversation with user"
)

Configuration Fact

add_memory(
    name="Config: Keycloak Realms",
    group_id="shakudo-platform-knowledge",
    episode_body="Shakudo Keycloak configuration: Production realm is 'hyperplane-dev' (not 'shakudo' or 'master'). Issuer URL: https://keycloak.dev.hyperplane.dev/realms/hyperplane-dev. Client IDs vary by app - check individual service configs. SKIP_AUTH=true bypasses Keycloak entirely for development.",
    source_description="key_facts.md"
)

System Knowledge

add_memory(
    name="System: FalkorDB Vector Index Requirements",
    group_id="shakudo-platform-knowledge",
    episode_body="FalkorDB requires explicit vector index creation for similarity search. If Graphiti searches return empty despite data existing, check if vector index exists. Create with: kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.QUERY <graph-name> \"CREATE VECTOR INDEX FOR (n:Entity) ON (n.name_embedding) OPTIONS {dimension: 1024, similarityFunction: 'cosine'}\". Dimension must match embedding model (1024 for text-embedding-3-small).",
    source_description="troubleshooting notes"
)

Recording Best Practices

1. Name Format: Use prefix to indicate type

   • Bug: [Brief description]
   • Decision: [What was decided]
   • Config: [Configuration area]
   • Customer: [Company name]
   • System: [Service/component]

2. Episode Body Structure:

   • Start with date (YYYY-MM-DD)
   • Include context/trigger
   • Explain root cause (for bugs)
   • Document solution with specifics (commands, code)
   • Note verification evidence
   • Mention alternatives considered (for decisions)

3. Source Description: Always cite where knowledge came from

   • bugs.md, decisions.md, key_facts.md
   • conversation with user
   • deployment logs
   • troubleshooting session

Dual Recording: Files + Graphiti

Record to BOTH file-based memory AND Graphiti.

Workflow

1. Fix and verify the problem
2. Record to appropriate file (bugs.md, decisions.md, etc.)
3. Record to Graphiti with add_memory()

Both sources are searched during mandatory lookup (grep for files, search_nodes for Graphiti).

Troubleshooting

Empty Results Despite Data Existing

1. Check group_ids: Are you passing 2+ group_ids? (See bug workaround above)
2. Check vector index: FalkorDB may be missing the vector index

# Check if vector index exists
kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.QUERY <graph-name> "CALL db.indexes()" | grep -i vector

# Create vector index if missing
kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.QUERY <graph-name> \
  "CREATE VECTOR INDEX FOR (n:Entity) ON (n.name_embedding) OPTIONS {dimension: 1024, similarityFunction: 'cosine'}"

Debug Commands

# List all graphs in FalkorDB
kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.LIST

# Count entities in a graph
kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.QUERY <graph-name> "MATCH (n:Entity) RETURN count(n)"

# List recent entities
kubectl exec -n hyperplane-falkordb <pod> -- redis-cli GRAPH.QUERY <graph-name> "MATCH (n:Entity) RETURN n.name LIMIT 10"

FalkorDB Pod Name

kubectl get pods -n hyperplane-falkordb -l app.kubernetes.io/name=falkordb -o name

Integration with AGENTS.md

This skill complements the mandatory memory protocols in AGENTS.md:

1. Before problem-solving: Search BOTH Graphiti AND files
2. After verified solution: Record to BOTH Graphiti AND files
3. Cite sources: "Found in Graphiti: [entity name]" or "Found in bugs.md: [entry]"

Quick Reference

# ALWAYS use 2+ group_ids for searches
SEARCH_GROUP_IDS = ["shakudo-platform-knowledge", "dummy"]

# Search for knowledge
search_nodes(query="your query", group_ids=SEARCH_GROUP_IDS, max_nodes=5)

# Record new knowledge (single group_id OK for writes)
add_memory(
    name="Type: Brief title",
    group_id="shakudo-platform-knowledge",
    episode_body="Date. Context. Details. Solution. Verified: evidence.",
    source_description="source"
)