shodh-memory

shodh-memory plugin for Cursor

2 skills

shodh-memory

Persistent memory system for AI agents. Use this skill to remember context across conversations, recall relevant information, and build long-term knowledge. Activate when you need to store decisions, learnings, errors, or context that should persist beyond the current session.

# Shodh Memory - Persistent Context for AI Agents

Shodh Memory gives you persistent memory across conversations. Unlike your context window which resets each session, memories stored here persist indefinitely and can be recalled semantically.

## When to Use Memory

**ALWAYS call `proactive_context` at the start of every conversation** with the user's first message. This surfaces relevant memories automatically.

### Store memories (`remember`) when:
- User makes a **decision** ("Let's use PostgreSQL for this project")
- You **learn** something new ("The codebase uses a monorepo structure")
- An **error** occurs and you find the fix
- You discover a **pattern** in the user's preferences
- Important **context** that will be useful later

### Recall memories (`recall`) when:
- User asks about past decisions or context
- You need to remember project-specific information
- Looking for patterns in how problems were solved before

## Memory Types

Choose the right type for better retrieval:

| Type | When to Use | Example |
|------|-------------|---------|
| `Decision` | User choices, architectural decisions | "User chose React over Vue for the frontend" |
| `Learning` | New knowledge gained | "This API requires OAuth2 with PKCE flow" |
| `Error` | Bugs found and fixes | "TypeError in auth.js fixed by null check" |
| `Discovery` | Insights, aha moments | "The performance issue was caused by N+1 queries" |
| `Pattern` | Recurring behaviors | "User prefers functional components over classes" |
| `Context` | Background information | "Working on e-commerce platform for client X" |
| `Task` | Work in progress | "Currently refactoring the payment module" |
| `Observation` | General notes | "User typically works in the morning" |

## Best Practices

### 1. Call `proactive_context` First

```
Every user message → call proactive_context with the message
```

This automatically:
- Retrieves relevant memories
- Stores the conversation context
- Builds association graph over time

### 2. Write Rich, Searchable Memories

**Good:**
```
"Decision: Use PostgreSQL with pgvector extension for the RAG application.
Reasoning: Need vector similarity search, user already has Postgres expertise,
avoids adding new infrastructure. Alternative considered: Pinecone (rejected
due to cost)."
```

**Bad:**
```
"Use postgres"
```

### 3. Use Tags for Organization

Tags enable fast filtering without semantic search:

```json
{
  "content": "API rate limit is 100 requests/minute",
  "tags": ["api", "rate-limit", "backend", "project-x"]
}
```

Later recall with: `recall_by_tags(["project-x", "api"])`

### 4. Memory Types Affect Importance

The system automatically weights memory types:
- `Decision` and `Error` → Higher importance, slower decay
- `Context` and `Observation` → Lower importance, faster decay

Choose types accurately for better long-term retention.

### 5. Leverage Different Recall Modes

| Mode | When to Use |
|------|-------------|
| `semantic` | Pure meaning-based search ("database optimization") |
| `associative` | Follow learned connections ("what else relates to X?") |
| `hybrid` | Best of both (default, recommended) |

## Common Patterns

### Starting a Session
```
1. User sends first message
2. Call proactive_context(context: user_message)
3. Review surfaced memories
4. Respond with relevant context
```

### After Making Progress
```
1. Complete a significant task
2. Call remember() with:
   - What was done
   - Why it was done
   - Key decisions made
   - Any gotchas discovered
```

### When User Asks "Do you remember..."
```
1. Call recall(query: "what user is asking about")
2. Also try recall_by_tags if you know relevant tags
3. Synthesize memories into response
```

### Debugging a Recurring Issue
```
1. recall(query: "error in [component]")
2. Check if similar errors were solved before
3. Apply previous fix or note new solution
4. remember() the resolution
```

## Memory Lifecycle

```
New Memory → Working Memory (hot, fast access)
            ↓ (consolidation)
         Session Memory (warm, recent context)
            ↓ (importance threshold)
         Long-term Memory (persistent, searchable)
```

The system automatically:
- Strengthens frequently-accessed memories
- Decays unused memories (but never fully forgets)
- Forms associations between co-retrieved memories
- Replays important memories during maintenance

## API Quick Reference

### Core Tools

| Tool | Purpose |
|------|---------|
| `proactive_context` | **Call every message.** Surfaces relevant memories, stores context |
| `remember` | Store a new memory |
| `recall` | Search memories by meaning |
| `recall_by_tags` | Filter memories by tags |
| `recall_by_date` | Filter memories by time range |
| `forget` | Delete a specific memory |
| `forget_by_tags` | Delete memories matching tags |

### Diagnostic Tools

| Tool | Purpose |
|------|---------|
| `memory_stats` | Get counts and health status |
| `context_summary` | Quick overview of recent learnings/decisions |
| `consolidation_report` | See what the memory system is learning |
| `verify_index` | Check index health |
| `repair_index` | Fix orphaned memories |

## Example Workflow

```
User: "Let's start building the user authentication system"

You:
1. proactive_context("Let's start building the user authentication system")
   → Surfaces: Previous auth decisions, security preferences, tech stack

2. Response incorporates remembered context:
   "Based on our earlier decision to use PostgreSQL and your preference
   for JWT tokens, I'll set up auth with..."

3. After implementation:
   remember(
     content: "Implemented JWT authentication with refresh token rotation.
               Used bcrypt for password hashing (cost factor 12).
               Tokens expire in 15 minutes, refresh tokens in 7 days.",
     type: "Learning",
     tags: ["auth", "jwt", "security", "user-system"]
   )
```

## Tips for Effective Memory

1. **Be specific** - "React 18 with TypeScript" not "frontend framework"
2. **Include reasoning** - Why decisions were made, not just what
3. **Tag consistently** - Use a tagging convention across the project
4. **Review periodically** - Use `context_summary` to see what's accumulated
5. **Trust the system** - It strengthens useful memories automatically

---

*Shodh Memory: Because context shouldn't reset with every conversation.*

orchestrate

--- name: orchestrate description: This skill should be used when the user asks to 'orchestrate a task', 'break down work into parallel agents', 'coordinate subtasks', 'run agents in parallel', or m

---
name: orchestrate
description: This skill should be used when the user asks to 'orchestrate a task', 'break down work into parallel agents', 'coordinate subtasks', 'run agents in parallel', or mentions 'multi-agent'. Decomposes complex tasks into tracked subtasks, dispatches parallel subagents, and coordinates until completion.
version: 1.0.0
author: Shodh AI
tags:
  - orchestration
  - multi-agent
  - parallel
  - task-decomposition
  - coordination
---

# Agent Orchestration — Todo-Driven Parallel Execution

You are orchestrating a complex task by decomposing it into tracked subtasks, dispatching parallel agents, and coordinating dependencies until completion. Shodh-memory todos are your task graph. Claude Code's Task tool is your agent spawner. Hooks handle the automation.

## Phase 1: Decompose

Break the user's request into 3-10 concrete, independently executable subtasks.

### Create the project

```
add_project(name="orch-{kebab-case-summary}")
```

The project auto-generates a prefix (e.g., `ORCH`). All todos in this project use that prefix for short IDs like `ORCH-1`, `ORCH-2`.

### Create todos with dependencies

For each subtask, create a todo in the project:

**Independent tasks** (can run immediately):
```
add_todo(
  content="Clear, specific description of what this subtask produces",
  project="orch-{name}",
  priority="high",
  tags=["orchestration", "batch:1"]
)
```

**Dependent tasks** (must wait for others):
```
add_todo(
  content="Description of dependent work",
  project="orch-{name}",
  status="blocked",
  blocked_on="ORCH-1,ORCH-3",
  tags=["orchestration", "batch:2"]
)
```

The `blocked_on` field is comma-separated short IDs. The `batch:N` tag groups tasks by execution wave.

### Dependency rules
- A task blocked on `"ORCH-1,ORCH-3"` cannot start until BOTH are done
- Keep dependency chains shallow (max 3-4 levels deep)
- Maximize parallelism — identify tasks that are truly independent
- Never create circular dependencies

### Present the plan

Show the user the task graph before executing:

```
Project: orch-refactor-auth (ORCH)

Batch 1 (parallel):
  ORCH-1: [todo] Extract JWT utilities into auth/tokens.ts
  ORCH-2: [todo] Create password hashing module

Batch 2 (after batch 1):
  ORCH-3: [blocked on ORCH-1] Update login endpoint
  ORCH-4: [blocked on ORCH-1] Update token refresh endpoint
  ORCH-5: [blocked on ORCH-2] Update registration endpoint

Batch 3 (after batch 2):
  ORCH-6: [blocked on ORCH-3,ORCH-4,ORCH-5] Integration tests
```

Wait for user approval before dispatching.

## Phase 2: Dispatch

### Find unblocked work

```
list_todos(project="orch-{name}", status=["todo"])
```

### For each unblocked todo:

1. Mark it in-progress:
```
update_todo(todo_id="ORCH-N", status="in_progress")
```

2. Spawn a Task agent with the todo tag in the prompt:

**CRITICAL:** Every Task prompt MUST start with `[ORCH-TODO:ORCH-N]` where N is the todo's sequence number. The PostToolUse hook extracts this tag to automatically complete the todo and unblock dependents.

```
Task(
  description="ORCH-N: brief summary",
  prompt="[ORCH-TODO:ORCH-N] Full detailed instructions for the agent...",
  subagent_type="general-purpose"
)
```

3. Spawn independent tasks in parallel — make multiple Task calls in a single response.

### Choose the right agent type

| Agent Type | Best For |
|---|---|
| `Explore` | Research, codebase exploration, finding patterns |
| `Plan` | Architecture design, trade-off analysis |
| `Bash` | Running commands, builds, deployments |
| `general-purpose` | Code changes, implementation, multi-step work |

### Include sufficient context in each prompt

Each agent runs in isolation. Include in every Task prompt:
- What files to look at or modify
- What the expected output/deliverable is
- Any constraints or patterns to follow
- Context from previously completed tasks (copy relevant resolution comments)

## Phase 3: Monitor & Continue

After agents return, the PostToolUse hook automatically:
- Adds the agent's result as a Resolution comment on the matching todo
- Completes the todo
- Unblocks dependent todos (removes from `blocked_on`, changes status to `todo`)

### Check project state

```
list_todos(project="orch-{name}")
```

Review the status:
- `done` — completed by agents
- `todo` — newly unblocked, ready for next batch
- `blocked` — still waiting on dependencies
- `in_progress` — agents still running
- `cancelled` — failed permanently

### Dispatch next batch

If there are `todo` status items, repeat Phase 2 for the next batch. Continue until all todos are `done` or `cancelled`.

### Summarize results

When all todos are complete:
1. List all resolution comments to gather agent outputs
2. Synthesize a summary for the user
3. Note any cancelled tasks and why

## Handling Failures

When a Task agent returns an error or incomplete result:

1. Add a Progress comment documenting the failure:
```
add_todo_comment(
  todo_id="ORCH-N",
  content="Agent failed: {error description}",
  comment_type="progress"
)
```

2. Retry (max 2 attempts) with additional context:
```
Task(
  prompt="[ORCH-TODO:ORCH-N] RETRY: Previous attempt failed because {reason}. {updated instructions}...",
  subagent_type="general-purpose"
)
```

3. If retry fails, cancel the todo:
```
update_todo(todo_id="ORCH-N", status="cancelled", notes="Failed after 2 retries: {reason}")
```

4. Check if cancelled todo blocks other work — inform the user and ask how to proceed.

## Cross-Session Continuity

If a session ends mid-orchestration, the todo state persists. On the next session:

1. Check for in-progress orchestration projects:
```
list_projects()
list_todos(project="orch-{name}")
```

2. Resume from where you left off — dispatch any `todo` status items.

## Example

User: `/orchestrate Add comprehensive error handling to the API layer`

**Planning:**
```
Project: orch-api-error-handling (ORCH)

ORCH-1: [todo] Audit current error handling patterns across all handlers
ORCH-2: [todo] Design error response format and error codes enum
ORCH-3: [blocked on ORCH-1,ORCH-2] Implement centralized error middleware
ORCH-4: [blocked on ORCH-3] Update all handler functions to use new error types
ORCH-5: [blocked on ORCH-4] Add error handling integration tests
```

**Batch 1 dispatch (parallel):**
```
Task("[ORCH-TODO:ORCH-1] Explore the codebase and audit...", subagent_type="Explore")
Task("[ORCH-TODO:ORCH-2] Design an error response format...", subagent_type="Plan")
```

**After batch 1 completes:**
- Hook auto-completes ORCH-1 and ORCH-2
- Hook unblocks ORCH-3 (both blockers resolved)
- Claude dispatches ORCH-3

**Continue until ORCH-5 is done.**