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

Unknown tool: mcp__contextd__*

/contextd:init

Connection refused on port 9090

contextd serve

Tenant not found

Input Validation Errors

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

invalid project_path: path contains directory traversal

../

invalid tenant_id: must be lowercase alphanumeric with underscores

my_project

org123

invalid project_id: must be lowercase alphanumeric with underscores

invalid include_patterns: contains dangerous characters

;

|

`

$

invalid patterns: excessive wildcards

***

*

**

*.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

semantic_search

repository_search

repository_index

memory_search

memory_record

memory_feedback

memory_outcome

checkpoint_save

checkpoint_list

checkpoint_resume

remediation_search

remediation_record

troubleshoot_diagnose

branch_create

branch_return

branch_status

reflect_analyze

reflect_report

Health Monitoring (HTTP)

contextd exposes HTTP health endpoints for monitoring vectorstore integrity:

GET /health

GET /api/v1/health/metadata

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

semantic_search

memory_search

Path Validation (contextd v1.5+)

All tools accepting

project_path

• 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

git remote get-url origin | sed 's|.*github.com[:/]\([^/]*\).*|\1|'

Project ID: Scopes memories. Use repository name (e.g.,

contextd

org_repo

ID Format Requirements (contextd v1.5+)

Both

tenant_id

project_id

• 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

semantic_search

memory_search

memory_record

remediation_search

branch_create

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

learning

remediation

decision

failure

pattern

policy

Tag memories with type:

tags: ["type:learning", "category:testing"]

Query Expansion & Fuzzy Matching

Automatic Query Expansion

semantic_search

memory_search

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:

created_by

created_at

updated_at

usage_count

last_used_at

Query audit data:

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

Claude Code 2.1 Patterns

Background Task Execution

Use

run_in_background: true

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