Use when starting any session with contextd - introduces core tools for cross-session memory, semantic code search, and error remediation. REQUIRES contextd MCP server.
Integrates cross-session memory and semantic code search to apply past learnings and solutions to new tasks.
/plugin marketplace add fyrsmithlabs/marketplace/plugin install contextd@fyrsmithlabsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill REQUIRES the contextd MCP server.
Before using any contextd tools, verify availability:
mcp__contextd__* tools (use ToolSearch if needed)/contextd:init to configure contextd"| 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 |
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 |
BEFORE any filesystem operation (Read, Grep, Glob), you MUST:
semantic_search(query, project_path: ".") - Semantic code search with auto grep fallbackmemory_search(project_id, query) - Check past learnings and solutionsSkipping this is a protocol violation.
| 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 |
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}}
| 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 |
All tools accepting project_path validate paths before use:
../ are rejectedsemantic_search, repository_index, repository_search, reflect_report1. 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)
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.
Both tenant_id and project_id must follow this format:
a-z, 0-9, _)my_project, contextd, org123, fyrsmithlabs_marketplaceMy-Project (uppercase, hyphen), org/repo (slash), project..name (dots)Confidence: Memories have scores (0-1) that adjust via feedback. Higher = ranks first.
Good memories:
Skip recording:
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"]
}
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.
| 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 |
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 timerExpiration policies:
ttl_days: 365 - Auto-archive after 1 year without activitynever_expire: true - For ADRs and critical decisions| 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"]
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
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 matchsemantic - Meaning matchfuzzy - Typo-tolerant matchStructure 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 memoriesfyrsmithlabs/platform/* - All platform teamfyrsmithlabs/platform/contextd - Specific projectAll 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
}
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)
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])
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."
}
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."
}
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 recordedmemory_feedback - Feedback givenremediation_recorded - New fix documentedcheckpoint_saved - State preservedExpert guidance for Next.js Cache Components and Partial Prerendering (PPR). **PROACTIVE ACTIVATION**: Use this skill automatically when working in Next.js projects that have `cacheComponents: true` in their next.config.ts/next.config.js. When this config is detected, proactively apply Cache Components patterns and best practices to all React Server Component implementations. **DETECTION**: At the start of a session in a Next.js project, check for `cacheComponents: true` in next.config. If enabled, this skill's patterns should guide all component authoring, data fetching, and caching decisions. **USE CASES**: Implementing 'use cache' directive, configuring cache lifetimes with cacheLife(), tagging cached data with cacheTag(), invalidating caches with updateTag()/revalidateTag(), optimizing static vs dynamic content boundaries, debugging cache issues, and reviewing Cache Component implementations.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.