topic-graph

name: topic-graph description: | Topic graph exploration for agent-memory. Use when asked to "explore topics", "show related concepts", "what themes have I discussed", "find topic connections", or "discover patterns in conversations". Provides semantic topic extraction with time-decayed importance scoring. license: MIT metadata: version: 1.0.0 author: SpillwaveSolutions

Topic Graph Skill

Semantic topic exploration using the agent-memory topic graph (Phase 14).

When to Use

When Not to Use

• Specific keyword search (use BM25)
• Exact phrase matching (use BM25)
• Current session context (already in memory)
• Cross-project queries (topic graph is per-project)

Quick Start

Prerequisites

memory-daemon status  # Check daemon
memory-daemon start   # Start if needed

Validation Checklist

Before presenting results:

• Daemon running: memory-daemon status returns "running"
• Topic graph enabled: topics status shows Enabled: true
• Topics populated: topics status shows Topics: > 0
• Query returns results: Check for non-empty topic list

Topic Graph Status

memory-daemon topics status

Output:

Topic Graph Status
----------------------------------------
Enabled:           true
Healthy:           true
Total Topics:      142
Active Topics:     89
Dormant Topics:    53
Last Extraction:   2026-01-30T15:42:31Z
Half-Life Days:    30

Explore Top Topics

Get the most important topics based on time-decayed scoring:

# Top 10 topics by importance
memory-daemon topics top --limit 10

# Include dormant topics
memory-daemon topics top --include-dormant

# JSON output for processing
memory-daemon topics top --format json

Output:

Top Topics (by importance)
----------------------------------------
1. authentication (importance: 0.892)
   Mentions: 47, Last seen: 2026-01-30

2. error-handling (importance: 0.756)
   Mentions: 31, Last seen: 2026-01-29

3. rust-async (importance: 0.698)
   Mentions: 28, Last seen: 2026-01-28

Query Topics

Find topics related to a query:

# Find topics matching query
memory-daemon topics query "JWT authentication"

# With minimum similarity
memory-daemon topics query "debugging" --min-similarity 0.7

Output:

Topics for: "JWT authentication"
----------------------------------------
1. jwt-tokens (similarity: 0.923)
   Related to: authentication, security, tokens

2. authentication (similarity: 0.891)
   Related to: jwt-tokens, oauth, users

Topic Relationships

Explore connections between topics:

# Get related topics
memory-daemon topics related --topic-id "topic:authentication"

# Get parent/child hierarchy
memory-daemon topics hierarchy --topic-id "topic:authentication"

# Get similar topics (by embedding)
memory-daemon topics similar --topic-id "topic:jwt-tokens" --limit 5

Topic-Guided Navigation

Use topics to navigate TOC:

# Find TOC nodes for a topic
memory-daemon topics nodes --topic-id "topic:authentication"

Output:

TOC Nodes for topic: authentication
----------------------------------------
1. toc:segment:abc123 (2026-01-30)
   "Implemented JWT authentication..."

2. toc:day:2026-01-28
   "Authentication refactoring complete..."

Configuration

Topic graph is configured in ~/.config/agent-memory/config.toml:

[topics]
enabled = true  # Enable/disable topic extraction
min_cluster_size = 3  # Minimum mentions for topic
half_life_days = 30  # Time decay half-life
similarity_threshold = 0.7  # For relationship detection

[topics.extraction]
schedule = "0 */4 * * *"  # Every 4 hours
batch_size = 100

[topics.lifecycle]
prune_dormant_after_days = 365
resurrection_threshold = 3  # Mentions to resurrect

Topic Lifecycle

Topics follow a lifecycle with time-decayed importance:

New Topic (mention_count: 1)
    |
    v  (more mentions)
Active Topic (importance > 0.1)
    |
    v  (time decay, no new mentions)
Dormant Topic (importance < 0.1)
    |
    v  (new mention)
Resurrected Topic (active again)

Lifecycle Commands

# View dormant topics
memory-daemon topics dormant

# Force topic extraction
memory-daemon admin extract-topics

# Prune old dormant topics
memory-daemon admin prune-topics --dry-run

Integration with Search

Topics integrate with the retrieval tier system:

Explore Workflow

# 1. Get top topics in area of interest
memory-daemon topics query "performance optimization"

# 2. Find TOC nodes for relevant topic
memory-daemon topics nodes --topic-id "topic:caching"

# 3. Navigate to specific content
memory-daemon query node --node-id "toc:segment:xyz"

Error Handling

Advanced: Time Decay

Topic importance uses exponential time decay:

importance = mention_count * 0.5^(age_days / half_life)

With default 30-day half-life:

• Topic mentioned today: full weight
• Topic mentioned 30 days ago: 50% weight
• Topic mentioned 60 days ago: 25% weight

This surfaces recent topics while preserving historical patterns.

Relationship Types

See Command Reference for full CLI options.