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

Error	Meaning	Fix
Unknown tool: mcp__contextd__*	MCP not configured	Run /contextd:init
Connection refused on port 9090	Server not running	Run contextd serve
Tenant not found	First use	Will auto-create

Input Validation Errors

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

Error	Cause	Fix
invalid project_path: path contains directory traversal	Path contains ../	Use absolute paths or paths within project
invalid tenant_id: must be lowercase alphanumeric with underscores	Invalid characters in ID	Use format: my_project, org123 (1-64 chars)
invalid project_id: must be lowercase alphanumeric with underscores	Invalid characters in ID	Same as tenant_id format
invalid include_patterns: contains dangerous characters	Shell injection chars in glob	Remove ;, |, `, $ from patterns
invalid patterns: excessive wildcards	Pattern like ***	Use standard globs: *, **, *.go

---

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

Category	Tools	Purpose
Search	semantic_search, repository_search, repository_index	Code lookup by meaning
Memory	memory_search, memory_record, memory_feedback, memory_outcome	Cross-session learning
Checkpoint	checkpoint_save, checkpoint_list, checkpoint_resume	Context preservation
Remediation	remediation_search, remediation_record, troubleshoot_diagnose	Error pattern tracking
Context Folding	branch_create, branch_return, branch_status	Isolated sub-tasks
Reflection	reflect_analyze, reflect_report	Behavior pattern analysis

Health Monitoring (HTTP)

contextd exposes HTTP health endpoints for monitoring vectorstore integrity:

Endpoint	Purpose	Status Codes
GET /health	Basic health with metadata summary	200 OK, 503 Degraded
GET /api/v1/health/metadata	Detailed per-collection status	200 OK

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

Priority	Tool	When
1st	semantic_search	Auto-selects best method (indexed or grep fallback)
2nd	memory_search	Have I solved this before?
3rd	Read/Grep/Glob	Fallback for exact matches only

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

Mistake	Fix
Using Read/Grep before contextd	semantic_search FIRST
Not searching at task start	Always memory_search first
Forgetting to record learnings	memory_record at task completion
Re-solving fixed errors	remediation_search when errors occur
Context bloat from sub-tasks	Use branch_create for isolation

---

Memory Lifecycle

Temporal Decay & Expiration

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

Age	Decay Factor	Result
< 7 days	1.0	Full confidence
7-30 days	0.9	Slight decay
30-90 days	0.7	Moderate decay
> 90 days	0.5	Significant decay (but never deleted)

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

Type	Purpose	Default TTL
learning	General knowledge gained	180 days
remediation	Error -> fix mappings	365 days
decision	ADR/architecture choices	Never
failure	What NOT to do	365 days
pattern	Reusable code patterns	180 days
policy	STRICT constraints	Never

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

---

Query Expansion & Fuzzy Matching

Automatic Query Expansion

semantic_search and memory_search automatically expand queries:

Original Query	Expanded To
"auth error"	"auth error", "authentication failure", "login issue", "401", "403"
"test fails"	"test fails", "test failure", "assertion error", "spec broken"
"slow query"	"slow query", "performance", "N+1", "timeout", "latency"

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:

Field	Description	Auto-set
created_by	Agent/session that created	Yes
created_at	ISO timestamp	Yes
updated_at	Last modification	Yes
usage_count	Times retrieved in searches	Yes
last_used_at	Last retrieval timestamp	Yes

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