Feature deep dive

Memory Graph for AI Agents

Map wiki-links, tags, and frontmatter relations into a typed knowledge graph so your agent retrieves connected context, not isolated snippets.

Flat memory lists lose relationship context. When agents store decisions, projects, and lessons as isolated records, they cannot follow reasoning chains between related concepts.

ClawVault builds a typed knowledge graph from wiki-links, tags, and frontmatter relations in your Markdown memory files. The graph index enables traversal-based retrieval that follows connections instead of relying on keyword proximity alone.

Install with npmView GitHub

Why teams lose context

  • •Isolated memory records miss important relationships between decisions.
  • •Keyword search cannot follow reasoning chains across related topics.
  • •Teams re-explain connections that should already be encoded in memory.
  • •Without graph structure, retrieval quality degrades as memory volume grows.

How ClawVault helps

  • •Extract wiki-links, tags, and frontmatter relations into a typed graph index.
  • •Traverse connections during retrieval to surface related context automatically.
  • •Combine graph-aware retrieval with semantic search for high-precision recall.
  • •Inspect and version the graph index alongside your memory files.

01Why graph structure improves agent memory

A knowledge graph encodes relationships that flat storage cannot represent. When an agent retrieves a decision, graph traversal surfaces the constraints, incidents, and preferences that informed it.

This matters most for complex projects where decisions interact. Graph-aware retrieval reduces the chance of recalling a conclusion without its supporting rationale.

02How ClawVault builds the memory graph

ClawVault scans your memory vault for wiki-links ([[target]]), tags, and frontmatter relations. It compiles these into a typed graph index stored at .clawvault/graph-index.json.

The graph tracks nodes (memory records) and edges (links between them), enabling traversal queries that follow relationship paths.

Build and query the memory graph
$clawvault graph
# Builds .clawvault/graph-index.json from wiki-links, tags, and frontmatter
$clawvault graph --stats
# Shows node count, edge count, and orphan detection
$clawvault graph --connections "auth-token-strategy"
# Lists all records linked to the auth token decision

03Graph-aware context retrieval

Standard retrieval returns individual records. Graph-aware retrieval also pulls connected nodes — the decisions, lessons, and constraints linked to the primary result.

This produces richer context injections without requiring the agent to issue multiple search queries.

Retrieve with graph traversal
$clawvault vsearch "billing architecture" --graph
# Returns the billing decision PLUS linked constraints, incidents, and preferences
$clawvault search "retry policy" --depth 2
# Follows links up to 2 hops from matching records

04Wiki-linking best practices

Consistent wiki-linking is the foundation of graph quality. Link decisions to their constraints, lessons to their incidents, and projects to their stakeholders.

  • •Use [[decision-name]] links in memory content to create explicit edges.
  • •Tag memories with consistent frontmatter categories for type-aware traversal.
  • •Run clawvault link --orphans periodically to find unlinked records.
  • •Treat the graph index as an engineering artifact worth reviewing.

Graph-aware retrieval vs flat memory search

Flat search finds individual records. Graph-aware retrieval follows connections to surface the full context around a topic.

CriterionClawVaultFlat memory search
Relationship awarenessTraverses wiki-links and tags between recordsReturns isolated matches without connection context
Context completenessSurfaces linked decisions, constraints, and lessonsRequires multiple manual queries to build full picture
Scaling behaviorGraph structure improves retrieval as memory growsNoise increases and precision drops with volume
InspectabilityGraph index is a local JSON file you can reviewNo explicit relationship model to audit

When should I use ClawVault?

  • •Use the memory graph when decisions depend on multiple related constraints and you need the full picture during retrieval.
  • •Use the memory graph when your vault grows beyond simple keyword search and relationships between records become important.
  • •Use the memory graph when teams need to trace how past decisions connect to current architecture.

Frequently asked questions

01What is a memory graph for AI agents?
A memory graph is a typed knowledge graph built from wiki-links, tags, and relations in your memory files. It enables retrieval that follows connections between related context.
02How does ClawVault build the knowledge graph?
ClawVault scans Markdown memory files for wiki-links, tags, and frontmatter relations, then compiles them into a graph index stored at .clawvault/graph-index.json.
03Does graph-aware retrieval replace semantic search?
No. They complement each other. Semantic search finds relevant records by meaning, and graph traversal expands results to include connected context.
04How do I maintain graph quality over time?
Use consistent wiki-link conventions, run orphan detection periodically, and review the graph index as part of regular memory maintenance.

Related guides

Structured Graph Categories

Organize memory records into queryable category groups.

Semantic Search Memory

Combine graph traversal with meaning-based retrieval.

Persistent Memory

Build durable recall loops on top of graph-linked records.

How OpenClaw Memory Works

Technical context for memory flow and retrieval quality.