Complete guide to [[entity]] syntax, intelligent file routing, entity-slug generation, and knowledge graph building in ClawVault.

Wiki-links and Entity Routing

ClawVault uses wiki-links to build a knowledge graph and intelligently route content to appropriate folders. This system turns simple [[entity]] references into a structured, interconnected memory system.

Wiki-link Syntax

Basic Links

# Simple entity reference
[[pedro]]

# Link with custom display text
[[pedro|Pedro Santos]]

# Link to specific section
[[database-decision#implementation]]

# Link with description
[[clawvault|ClawVault memory system]]

Entity Types

# People
[[pedro]], [[justin-dukes]], [[engineering-team]]

# Projects 
[[clawvault]], [[hale-pet-door]], [[api-redesign]]

# Decisions
[[database-choice]], [[architecture-patterns]], [[vendor-selection]]

# Concepts and lessons
[[context-death-recovery]], [[api-rate-limiting]], [[meeting-facilitation]]

Entity-Slug Generation

ClawVault converts entity names to consistent file paths using slug generation:

Conversion Rules

Original Name → Slug → File Path

"Pedro Santos" → pedro-santos → people/pedro-santos.md
"API Redesign Project" → api-redesign-project → projects/api-redesign-project.md 
"Database Choice Decision" → database-choice-decision → decisions/database-choice-decision.md
"Q1 2024 Goals" → q1-2024-goals → goals/q1-2024-goals.md

Slug Algorithm

Lowercase: Convert to lowercase
Replace spaces: Spaces become hyphens
Remove special chars: Keep only letters, numbers, hyphens
Collapse hyphens: Multiple hyphens become single hyphen
Trim: Remove leading/trailing hyphens

Examples

Input: "John Smith (Manager)" 
Output: john-smith-manager

Input: "API v2.0 Design"
Output: api-v2-0-design

Input: "Meeting: Q1 Planning & Review"
Output: meeting-q1-planning-review

Smart Entity Routing

When you reference an entity that doesn't exist, ClawVault routes it to the appropriate folder based on context and type detection:

Routing Logic

People Detection

# These patterns route to people/
[[pedro]] → people/pedro.md
[[Dr. Smith]] → people/dr-smith.md 
[[Engineering Team]] → people/engineering-team.md

# Context clues
Met with [[jane]] about the project.
[[sarah|Sarah from marketing]] sent feedback.

Project Detection

# These patterns route to projects/
[[clawvault]] → projects/clawvault.md
[[Pet Door App]] → projects/pet-door-app.md
[[Website Redesign]] → projects/website-redesign.md

# Context clues
Working on [[mobile-app]] this week.
The [[infrastructure upgrade]] is complete.

Decision Detection

# These patterns route to decisions/
[[database-choice]] → decisions/database-choice.md
[[vendor-selection]] → decisions/vendor-selection.md
[[architecture-decision]] → decisions/architecture-decision.md

# Context clues 
We [[decided to use PostgreSQL]] for better performance.
The [[choice to migrate]] was based on scalability.

Lesson Detection

# These patterns route to lessons/
[[context-death-recovery]] → lessons/context-death-recovery.md
[[meeting facilitation]] → lessons/meeting-facilitation.md
[[code-review-process]] → lessons/code-review-process.md

# Context clues
[[learned that]] checkpoints prevent context loss.
[[key insight]]: Always validate assumptions.

Routing Ambiguity Resolution

When routing is ambiguous, ClawVault uses these signals:

Existing files: If people/pedro.md exists, [[pedro]] links there
Context clues: Surrounding text suggests entity type
Capitalization: Proper names suggest people
Keywords: "Project", "Team", "Decision" in the name
Default routing: Unknown entities go to inbox/ for manual processing

Entity Subfolders

For complex entities, ClawVault supports subfolder routing:

People Subfolders

# Simple person record
[[pedro]] → people/pedro.md

# Complex person with subfolder
[[pedro]] → people/pedro/index.md
 └─ people/pedro/meeting-history.md
 └─ people/pedro/project-collaboration.md

Project Subfolders

# Simple project
[[clawvault]] → projects/clawvault.md

# Complex project with subfolder 
[[clawvault]] → projects/clawvault/index.md
 └─ projects/clawvault/technical-decisions.md
 └─ projects/clawvault/roadmap.md
 └─ projects/clawvault/meeting-notes.md

Subfolder Creation Strategy

ClawVault creates subfolders when:

Entity has more than 3 related files
Entity observations exceed size threshold
Manual subfolder creation via mkdir people/pedro/

Observation Routing

The observational memory system uses entity routing for auto-generated content:

People Observations

# Session contains: "Discussed API design with Pedro"
→ Routes to: people/pedro/2024-01-15.md

# Content
## Interaction with Pedro (2024-01-15)
- Discussed API design patterns
- Reviewed performance requirements 
- Next meeting scheduled for Friday

Project Observations

# Session contains: "Made progress on ClawVault documentation"
→ Routes to: projects/clawvault/2024-01-15.md

# Content
## ClawVault Progress (2024-01-15)
- Completed commands documentation
- Started OpenClaw integration guide
- Need to add more examples

Decision Observations

# Session contains: "Decided to use PostgreSQL over SQLite"
→ Routes to: decisions/database-choice.md

# Content (appended)
## Implementation Update (2024-01-15)
- Confirmed PostgreSQL choice
- Migration scripts in progress
- Performance testing scheduled

Auto-linking

ClawVault can automatically convert entity mentions into wiki-links:

Manual Linking

# Link all files in vault
clawvault link --all

# Link specific file 
clawvault link memory/2024-01-15.md

Auto-linking Algorithm

Scan text for entity patterns
Check existing entities in the vault
Apply context rules to avoid false positives
Convert mentions to [[entity]] format
Preserve context - don't link mid-word or in code blocks

Before Auto-linking

Met with Pedro today about the ClawVault improvements.
We discussed the database decision and decided to use PostgreSQL.
Sarah from the engineering team will help with testing.

After Auto-linking

Met with [[pedro]] today about the [[clawvault]] improvements.
We discussed the [[database-decision]] and decided to use PostgreSQL.
[[sarah]] from the [[engineering-team]] will help with testing.

Knowledge Graph Building

Wiki-links create edges in ClawVault's memory graph:

Graph Relationships

# File: people/pedro.md contains:
Works on [[clawvault]] and [[hale-pet-door]] projects.
Collaborated on [[database-decision]].

# Creates edges:
pedro → works_on → clawvault
pedro → works_on → hale-pet-door 
pedro → participated_in → database-decision

Graph Statistics

clawvault graph

Output:

 Memory Graph Summary

Nodes: 347 entities
 └─ People: 23
 └─ Projects: 12
 └─ Decisions: 45
 └─ Lessons: 38
 └─ Other: 229

Edges: 1,204 relationships
 └─ mentions: 892
 └─ works_on: 156
 └─ decided_in: 89
 └─ learned_from: 67

Top connected entities:
 1. [[pedro]] (47 connections)
 2. [[clawvault]] (34 connections)
 3. [[engineering-team]] (28 connections)

Link Management

Finding Broken Links

clawvault link --orphans

Output:

 Orphaned Wiki-Links Found:

memory/2024-01-10.md:
 Line 15: [[client-onboarding]] → people/client-onboarding.md (missing)
 Line 23: [[api-design]] → decisions/api-design.md (missing)

Total: 2 orphaned links in 1 file

 Suggestions:
 - Create people/client-onboarding.md for client process
 - Create decisions/api-design.md for API decisions

Finding Backlinks

clawvault link --backlinks people/pedro.md

Output:

 Backlinks to people/pedro.md:

decisions/database-choice.md:12 "discussed with [[pedro]]"
projects/clawvault.md:8 "[[pedro]] leads development"
memory/2024-01-15.md:23 "meeting with [[pedro]]"
handoffs/2024-01-14.md:15 "hand off to [[pedro]]"

Total: 4 files link to pedro

Advanced Routing Configuration

Entity routing is determined by the remember command's type parameter and the vault's category structure. There is no separate config set or route command — routing is implicit based on the memory type you specify:

# Route to people/ category
clawvault remember relationship "Pedro" --content "..."

# Route to projects/ category
clawvault remember project "ClawVault" --content "..."

# Route to decisions/ category
clawvault remember decision "Database Choice" --content "..."

# Route to lessons/ category
clawvault remember lesson "Caching Insight" --content "..."

To customize category directories, use --categories during clawvault init or edit .clawvault.json directly.

Best Practices

Naming Conventions

People: Use real names or consistent nicknames - pedro, dr-smith
Projects: Use project/product names - clawvault, hale-pet-door
Decisions: Be specific - database-choice-2024, not just database
Concepts: Use descriptive names - context-death-recovery, not just recovery

Link Strategy

# Good: specific, descriptive
[[pedro-santos|Pedro]], our [[lead-engineer]], decided on [[postgres-migration]].

# Avoid: vague, generic
[[person]] from [[team]] made a [[choice]].

Folder Organization

# Start simple
people/pedro.md
projects/clawvault.md

# Evolve to subfolders when needed
people/pedro/index.md
people/pedro/meeting-notes.md
projects/clawvault/index.md
projects/clawvault/technical-specs.md

Troubleshooting

Links Not Auto-creating

Problem: Mentions aren't converting to links

Solutions:

# Run linking manually
clawvault link --all

# Check entity detection
clawvault entities

# Check for orphaned/broken links
clawvault link --orphans

Wrong Routing Destination

Problem: Entities going to wrong folders

Solutions: Move the file manually to the correct category directory. ClawVault uses directory-based routing — the category is determined by which folder the file lives in.

Broken Link Explosion

Problem: Too many orphaned links after reorganization

Solutions:

# Find and fix in bulk
clawvault link --orphans --fix

# Use link replacement
clawvault link --replace "old-entity" "new-entity"

# Regenerate graph after fixes
clawvault graph --refresh

The wiki-link and entity routing system creates a self-organizing knowledge base that grows more valuable as you add content. The key is consistent usage and periodic maintenance to keep links clean and routing accurate.

Wiki-links and Entity Routing

On this page