using-graph-memory

Using graph memory

A Zep MCP server provides a temporal knowledge graph: facts are relations between entities, each carrying provenance and a validity interval. This skill covers how to store and query them in a way that survives audit.

Query — before acting on any entity

When the task involves an entity (a customer, account, policy, ticket), query the graph for what it knows about that entity first.

• Ask for multi-hop context when needed — follow relations rather than asking for one isolated fact.
• When history matters, ask for the state as of a specific date. The graph can answer "what was the credit limit on 2026-01-10", not just "now".
• Each returned fact carries its source and time. Surface that provenance to the user when it informs a decision; do not present a fact as bare truth.

Store — with provenance, always

When you learn a durable fact, store it via the MCP. Every stored fact must include:

• The fact — a clear subject-relation-object statement.
• The source — where it came from (a document, a user statement, a system of record). A fact with no source must not be stored.
• The observation time — when the fact was stated or became true.

If you cannot supply a source, you do not have a fact — you have a guess. Do not store guesses.

Updating facts — supersede, never overwrite

When a fact changes (a customer moves, a policy is revised):

• Store the new fact with its own source and time.
• The graph marks the prior fact as no longer valid from that point; it is retained, not deleted. This is what makes point-in-time queries and audit possible.
• Never edit a past fact to make it "current" — that destroys the history a regulated review depends on.

What stays out of the graph

• Conventions, architecture, build commands → CLAUDE.md.
• Code decisions and incidents → .claude/memory/*.md.
• Secrets and credentials → nowhere.

The graph is for evolving, provenance-bearing domain facts. Keep code-shaped knowledge in files where it is cheap and PR-reviewable.

MCP setup (opt-in)

This skill needs the Zep MCP server. It is not auto-started by the plugin — add it to your project's .mcp.json only if you want a knowledge graph, then set ZEP_API_KEY (and ZEP_API_URL for self-hosted) in your environment:

{
  "mcpServers": {
    "zep": {
      "command": "npx",
      "args": ["-y", "@getzep/zep-mcp-server"],
      "env": { "ZEP_API_KEY": "${ZEP_API_KEY}", "ZEP_API_URL": "${ZEP_API_URL}" }
    }
  }
}