Using Contextd

Using contextd

Prerequisites: contextd MCP Server

This skill REQUIRES the contextd MCP server.

Before using any contextd tools, verify availability:

1. Check for mcp__contextd__* tools (use ToolSearch if needed)
2. If tools are NOT available:
   • Inform user: "contextd MCP server not configured"
   • Suggest: "Run /contextd:init to configure contextd"
   • Alternative: Use standard Read/Grep/Glob (no cross-session memory)

Error Handling

Input Validation Errors

contextd v1.5+ enforces strict input validation. Common errors:

Pre-Flight Protocol (MANDATORY)

BEFORE any filesystem operation (Read, Grep, Glob), you MUST:

1. semantic_search(query, project_path: ".") - Semantic code search with auto grep fallback
2. memory_search(project_id, query) - Check past learnings and solutions

Skipping this is a protocol violation.

Core Tools

Health Monitoring (HTTP)

contextd exposes HTTP health endpoints for monitoring vectorstore integrity:

Graceful Degradation (P0): If corrupt collections are detected, contextd quarantines them and continues operating with healthy collections. Check health status to detect degraded state.

Example health check:

curl -s http://localhost:9090/health | jq
# {"status":"ok","metadata":{"status":"healthy","healthy_count":22,"corrupt_count":0}}

Search Priority

Path Validation (contextd v1.5+)

All tools accepting project_path validate paths before use:

• No directory traversal: Paths containing ../ are rejected
• Affected tools: semantic_search, repository_index, repository_search, reflect_report
• Use absolute paths or paths within the current project directory

The Learning Loop

1. SEARCH at task start (MANDATORY)
   semantic_search(query, project_path)
   memory_search(project_id, query)

2. DO the work
   (apply relevant memories)

3. RECORD at completion
   memory_record(project_id, title, content, outcome)

4. FEEDBACK when memories helped
   memory_feedback(memory_id, helpful)

Key Concepts

Tenant ID: Derived from git remote (e.g., github.com/fyrsmithlabs/contextd -> fyrsmithlabs). Verify with: git remote get-url origin | sed 's|.*github.com[:/]\([^/]*\).*|\1|'

Project ID: Scopes memories. Use repository name (e.g., contextd) or org_repo format for multi-org.

ID Format Requirements (contextd v1.5+)

Both tenant_id and project_id must follow this format:

• Characters: Lowercase alphanumeric and underscores only (a-z, 0-9, _)
• Length: 1-64 characters
• Valid: my_project, contextd, org123, fyrsmithlabs_marketplace
• Invalid: My-Project (uppercase, hyphen), org/repo (slash), project..name (dots)

Confidence: Memories have scores (0-1) that adjust via feedback. Higher = ranks first.

What to Record

Good memories:

• Non-obvious solutions
• Patterns that apply broadly
• Design decisions with rationale (the WHY)
• Mistakes and why they failed

Skip recording:

• Trivial fixes (typos, syntax)
• Project-specific details (put in CLAUDE.md)

Recording Design Decisions

When design involves significant discussion, capture the WHY:

{
  "project_id": "contextd",
  "title": "ADR: Registry pattern for DI",
  "content": "DECISION: Use Registry interface.\nWHY: Idiomatic Go, single mock for tests.\nREJECTED: Passing individual services (constructor bloat).",
  "outcome": "success",
  "tags": ["adr", "architecture", "design-decision"]
}

Optional: Conversation Indexing

Index past Claude Code sessions to pre-warm contextd:

# Via /init command
/init --conversations

# What it extracts:
# - Error -> fix patterns (remediations)
# - Learnings (memories)
# - User corrections (policies)

Conversations are scrubbed for secrets before processing.

Common Mistakes

Memory Lifecycle

Temporal Decay & Expiration

Memories have a confidence score (0-1) that decays over time without reinforcement:

Boost confidence via:

• memory_feedback(memory_id, helpful=true) - Resets decay timer
• Memory reuse in solutions - Auto-boosted when applied

Expiration policies:

• ttl_days: 365 - Auto-archive after 1 year without activity
• never_expire: true - For ADRs and critical decisions

Memory Types

Tag memories with type: tags: ["type:learning", "category:testing"]

Query Expansion & Fuzzy Matching

Automatic Query Expansion

semantic_search and memory_search automatically expand queries:

Disable expansion: expand_query: false

Fuzzy Matching

Handles typos and variations:

{
  "query": "authetication",
  "fuzzy_threshold": 0.8,  // 0-1, higher = stricter
  "fuzzy_max_edits": 2     // Levenshtein distance
}

Results include match quality:

• exact - Literal match
• semantic - Meaning match
• fuzzy - Typo-tolerant match

Hierarchical Namespaces

Structure project IDs for multi-team organizations:

org/team/project/module

Examples:
  fyrsmithlabs/platform/contextd/api
  fyrsmithlabs/platform/contextd/vectorstore
  fyrsmithlabs/marketplace/fs-dev

Search scopes:

• fyrsmithlabs/* - All org memories
• fyrsmithlabs/platform/* - All platform team
• fyrsmithlabs/platform/contextd - Specific project

Audit Fields

All memory operations record:

Query audit data:

{
  "query": "authentication",
  "include_audit": true
}

Claude Code 2.1 Patterns

Background Task Execution

Use run_in_background: true for long-running searches:

Task(
  subagent_type: "general-purpose",
  prompt: "Search memories for authentication patterns across all projects",
  run_in_background: true
)

// Continue other work...

// Later, collect results:
TaskOutput(task_id, block: true)

Task Dependencies with addBlockedBy

Chain dependent memory operations:

task1 = Task(prompt: "Index repository")
task2 = Task(prompt: "Search indexed code", addBlockedBy: [task1.id])
task3 = Task(prompt: "Record findings", addBlockedBy: [task2.id])

PreToolUse Hook Example

Auto-search memories before any Read operation:

{
  "hook_type": "PreToolUse",
  "tool_name": "Read",
  "prompt": "Before reading {{tool_input.file_path}}, search memories for relevant context about this file or module."
}

PostToolUse Hook Example

Auto-record learnings after successful operations:

{
  "hook_type": "PostToolUse",
  "tool_name": "Edit",
  "condition": "tool_output.success == true",
  "prompt": "If this edit fixed a bug or implemented a pattern worth remembering, call memory_record."
}

Event-Driven State Sharing

Skills can share state via memory events:

{
  "event": "memory_created",
  "filter": {"tags": ["type:decision"]},
  "notify": ["consensus-review", "self-reflection"]
}

Subscribe to events:

• memory_created - New memory recorded
• memory_feedback - Feedback given
• remediation_recorded - New fix documented
• checkpoint_saved - State preserved