Memory Relations and Graphs — Connecting Your Agent's Knowledge Into a Web

Your agent stores hundreds of memories over time. Decisions, corrections, preferences, project context. But individually, memories are just disconnected facts floating in a void. The real power comes when your agent can trace why a decision was made, what contradicts it, and how pieces of knowledge connect.

That’s what MemoClaw’s relations and graph APIs do. And they’re completely free.

What Are Memory Relations?

A relation is a typed link between two memories. Think of it like drawing an arrow on a whiteboard between two sticky notes, with a label explaining the connection.

MemoClaw supports five relation types:

  • related_to — General connection. Example: “Project deadline” ↔ “Team capacity”
  • derived_from — One memory came from another. Example: “Summary” ← “Raw session notes”
  • contradicts — These two memories conflict. Example: “User prefers dark mode” ⚡ “User said light mode is fine”
  • supersedes — Newer memory replaces older. Example: “New API endpoint” → replaces “Old API endpoint”
  • supports — Evidence backing a fact. Example: “PostgreSQL decision” ← “Team has pg expertise”

Relations are directional (source → target), but when you query them, you get both incoming and outgoing links.

Creating Relations With the CLI

Let’s walk through a real scenario. Your agent made a tech stack decision, and you want to link it to the reasoning behind it.

# Store the decision
memoclaw store "Decided to use SQLite for the mobile app's local cache" \
  --importance 0.9 --tags decision,architecture
# → Stored memory: mem_abc123

# Store the supporting reasoning
memoclaw store "SQLite chosen because it's embedded, zero-config, and handles our read-heavy workload well" \
  --importance 0.8 --tags reasoning,architecture
# → Stored memory: mem_def456

memoclaw store "Considered Redis but rejected — too complex for mobile, requires separate process" \
  --importance 0.6 --tags reasoning,architecture
# → Stored memory: mem_ghi789

Now link them:

# The reasoning supports the decision
curl -X POST https://api.memoclaw.com/v1/memories/mem_abc123/relations \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "mem_def456",
    "relation_type": "supports",
    "metadata": { "context": "tech stack evaluation Q1 2026" }
  }'

# The rejected alternative is related
curl -X POST https://api.memoclaw.com/v1/memories/mem_abc123/relations \
  -H "Content-Type: application/json" \
  -d '{
    "target_id": "mem_ghi789",
    "relation_type": "related_to"
  }'

Your agent now knows what was decided, why, and what was rejected. Months later, when someone asks “why didn’t we use Redis?”, semantic recall plus graph traversal gives the full picture.

Traversing the Knowledge Graph

The graph endpoint is where things get interesting. Starting from any memory, you can explore outward N hops to discover connected knowledge:

curl "https://api.memoclaw.com/v1/memories/mem_abc123/graph?depth=2"

This returns three things:

  1. root — the starting memory
  2. nodes — all memories discovered within 2 hops
  3. edges — the relationships connecting them
{
  "root": {
    "id": "mem_abc123",
    "content": "Decided to use SQLite for the mobile app's local cache",
    "importance": 0.9
  },
  "nodes": [
    {
      "id": "mem_def456",
      "content": "SQLite chosen because it's embedded, zero-config..."
    },
    {
      "id": "mem_ghi789",
      "content": "Considered Redis but rejected..."
    }
  ],
  "edges": [
    { "source_id": "mem_abc123", "target_id": "mem_def456", "relation_type": "supports" },
    { "source_id": "mem_abc123", "target_id": "mem_ghi789", "relation_type": "related_to" }
  ],
  "depth": 2
}

You can filter by relation type too:

# Only follow "contradicts" edges — find conflicts
curl "https://api.memoclaw.com/v1/memories/mem_abc123/graph?depth=3&relation_types=contradicts"

Practical Patterns

1. Decision Audit Trail

Every time your agent makes or records a decision, link it to its supporting evidence:

# Decision → supports → Evidence 1
# Decision → supports → Evidence 2
# Decision → related_to → Rejected alternative

When someone questions the decision months later, traverse the graph from the decision node and you get the full context without any semantic search ambiguity.

2. Correction Chains

Users correct agents. A lot. Track the evolution:

# Store the correction
memoclaw store "User prefers deployment notifications in #ops, NOT #general" \
  --importance 0.95 --tags correction,preferences

# Link it to what it replaces
curl -X POST https://api.memoclaw.com/v1/memories/NEW_MEM_ID/relations \
  -d '{"target_id": "OLD_MEM_ID", "relation_type": "supersedes"}'

Now your agent has a clear chain: current preference → supersedes → old preference. No more accidentally reverting to outdated info.

3. Session Summary Networks

If your agent stores session summaries, link consecutive sessions:

# Today's summary derives from yesterday's context
curl -X POST https://api.memoclaw.com/v1/memories/TODAYS_SUMMARY/relations \
  -d '{"target_id": "YESTERDAYS_SUMMARY", "relation_type": "derived_from"}'

This creates a timeline you can walk backward through — useful for understanding how a project evolved.

4. Multi-Agent Knowledge Linking

When agents share a wallet (and thus a memory space), relations let them cross-reference each other’s knowledge:

# Architect agent stores a design decision
# Coder agent stores implementation details
# Link them: implementation supports design

curl -X POST https://api.memoclaw.com/v1/memories/IMPLEMENTATION_MEM/relations \
  -d '{"target_id": "DESIGN_MEM", "relation_type": "derived_from"}'

Relations vs Tags vs Namespaces

These three organize memories differently. Use them together:

  • Tags — categorize individual memories (what type of memory is this?)
  • Namespaces — isolate groups of memories (which project does this belong to?)
  • Relations — connect memories to each other (how do these relate?)

A memory tagged decision in namespace mobile-app that’s linked via supports to three evidence memories — that’s the full picture. Tags tell you what it is, namespaces tell you where it belongs, relations tell you why it matters.

Cost: Zero

Relations are entirely free. Creating, listing, deleting, and traversing the graph — none of it costs anything. They don’t use embeddings or LLM calls, so there’s no OpenAI cost to pass through.

This makes relations one of the best bang-for-zero-bucks features in MemoClaw. You’re adding structure and context to your agent’s knowledge without spending a single free-tier call.

Building a Knowledge Web Over Time

The real value of relations compounds over time. A single memory is a fact. A related cluster is understanding. A traversable graph is institutional knowledge.

Start small:

  1. Link corrections to what they replace (supersedes)
  2. Link decisions to their reasoning (supports)
  3. Link related project context (related_to)

As your agent’s graph grows, recall becomes more powerful — not just finding relevant memories by meaning, but understanding the structure of what it knows.

Your agent doesn’t just remember things. It understands how they connect.

Resources: