--- name: graph-memory description: Long-term relational/graph memory via Zep Cloud knowledge graph. ADDITIVE layer on top of OpenClaw builtin vector memory (memory-core) — never replaces it. Use to store and recall RELATIONSHIPS, entities, evolving facts over time (people, projects, decisions, who-relates-to-whom). Vector memory stays primary for semantic recall; Zep graph adds entity/edge reasoning. Zero performance impact: called on-demand only, never in hot path. ---

Graph Memory Skill (Zep Cloud)

Philosophy (per Dr. Wael 2026-06-01)

• ADDITIVE, never destructive. OpenClaw memory-core (vector) + memory-wiki stay the PRIMARY recall layer.
• Zep knowledge graph is a second layer for relational/temporal reasoning: entities, edges, evolving facts.
• Zero performance hit: on-demand only. NOT in heartbeat, NOT in every turn. Called when a query is clearly relational/long-term.
• The golden chain + arsenal are untouched. This only strengthens recall.

When to use

• Recall about relationships ("who is X to Y", "what decision did we make about Z and why")
• Evolving facts over time (prices, statuses, project state that changes)
• Cross-session entity continuity (people, KCPC projects, Empire Avcılar, family graph)

When NOT to use

• Simple semantic recall → use builtin memory_search (faster, primary)
• Anything in heartbeat / hot path
• Secrets / KCPC-sensitive data unless Dr. Wael explicitly approves (ask first per Ollama-style rule)

Engine (verified live 2026-06-01)

• Zep Cloud, ZEP_API_KEY in env.sh
• SDK: zep-cloud (pip, installed)
• healthz: HTTP 200 ✅ | user.add ✅ | graph.add ✅ | graph.search nodes ✅ (edges build async ~minutes)
• Default user_id: wael_main

Usage

bash
add a fact/relationship to the graph
python3 skills/graph-memory/zep_memory.py add "fact text describing entities/relations"
recall relational info
python3 skills/graph-memory/zep_memory.py search "who is Jihan best friend"
add a full conversation message (auto entity extraction)
python3 skills/graph-memory/zep_memory.py message "user said ..." --role user

Notes

• Graph extraction is async; edges appear after a few minutes. Nodes (entities) appear faster.
• Use --user <id> to scope (default wael_main).
• This is a recall AID. MEMORY.md + memory/*.md remain the source of truth on disk.