PROACTIVELY use this skill to capture full workflows, decisions, patterns, and project learnings. ACTIVELY use this skill to search memory before starting complex tasks. Triggers include 'remember this', 'what do we know about', 'search memory', 'save decision'.
This skill inherits all available tools. When active, it can use any tool Claude has access to.
checklists/session-end.mdchecklists/session-start.mdcognee-server.mdexamples/workflows.tsreferences/search-types.mdreferences/token-optimization.mdreferences/tool-reference.mdPersistent knowledge graph memory for coding decisions, patterns, and project learning.
IMPORTANT: Local Staging vs Direct API Hooks (post-commit, session-end) stage files locally to
~/.cognee-memory/for later import. Claude sessions use MCPcall_tool_chainfor direct graph operations. These are intentionally separate - hooks avoid API calls during git operations.
Skip loading this skill for:
| Command | Purpose |
|---|---|
/mem-save [topic] | Explicitly save a decision/learning to graph |
/mem-search [query] | Search prior context when needed |
/mem-import | Batch import staged local files |
Philosophy: Don't choose between "capture everything" (noisy) and "manual only" (forgotten). Layer them:
| Layer | What | Automation | Graph Impact |
|---|---|---|---|
| 1. Safety Net | Session transcripts | Auto-saved locally | None (not indexed) |
| 2. Deterministic | High-signal commits | Auto-indexed on fix/feat/refactor | Curated signal |
| 3. Explicit | Developer insights | /mem-save command | Highest value |
~/.cognee-memory/sessions//mem-import~/.cognee-memory/commits/fix:, feat:, refactor:, BREAKING, PR merges/mem-importAlways use MCP call_tool_chain for Cognee operations during Claude sessions.
Note: Examples use
cognee.cognee_*shorthand. In practice, invoke via:mcp__utcp-codemode__call_tool_chain({ tool_chain: `cognee.cognee_search({ search_query: "...", search_type: "CHUNKS" })` })
The Cognee MCP server is registered with MCP, so all tools use cognee.cognee_* namespace:
// Search
await cognee.cognee_search({
search_query: "invoice patterns",
search_type: "CHUNKS"
});
// Store
await cognee.cognee_cognify({
data: "## Decision: ..."
});
// Check status
await cognee.cognee_cognify_status({});
/mem-search) When:/mem-save) When:What do I need?
|
+-- Exact location/definition?
| └── CHUNKS (fastest, no LLM, ~0 extra tokens)
|
+-- Quick overview/summary?
| └── SUMMARIES (pre-computed, fast)
|
+-- Code patterns/functions?
| └── CODE (syntax-aware, medium speed)
|
+-- Complex reasoning/relationships?
| └── GRAPH_COMPLETION (LLM + graph, thorough)
|
+-- Traditional RAG (no graph)?
| └── RAG_COMPLETION (LLM + chunks only)
|
+-- Unsure what I need?
└── FEELING_LUCKY (auto-select)
| Query Type | Search Type | Token Cost | Example |
|---|---|---|---|
| "Where is X defined?" | CHUNKS | ~0 | Find specific code |
| "What does module X do?" | SUMMARIES | ~0 | Get overview |
| "Auth functions" | CODE | Low | Find functions |
| "How do X and Y interact?" | GRAPH_COMPLETION | High | Complex analysis |
| "Find info about X" | FEELING_LUCKY | Varies | General queries |
call_tool_chain)| Task | MCP Tool | Key Parameters |
|---|---|---|
| Store text/decisions | cognee.cognee_cognify | data: string |
| Query (fast) | cognee.cognee_search | search_type: "CHUNKS" |
| Query (thorough) | cognee.cognee_search | search_type: "GRAPH_COMPLETION" |
| Check progress | cognee.cognee_cognify_status | none |
| Log Q&A pair | cognee.cognee_save_interaction | data: "Q: ... A: ..." |
Complete tool reference: See references/tool-reference.md for all 11 tools including
codify,delete,prune,list_data, and developer rules management.
Start with CHUNKS (free)
→ If insufficient, try SUMMARIES
→ If still need more, use GRAPH_COMPLETION
When to skip:
// DON'T: Multiple separate cognify calls
await cognee.cognee_cognify({ data: "Decision 1" });
await cognee.cognee_cognify({ data: "Decision 2" });
// DO: Single batched call
await cognee.cognee_cognify({
data: `
## Decision 1: [title]
[content]
## Decision 2: [title]
[content]
`
});
// After adding new data, verify processing complete
const status = await cognee.cognee_cognify_status({});
// Only search if status shows completion
Don't re-search for the same query within a session. Reference prior results.
// Fast search for relevant context
const context = await cognee.cognee_search({
search_query: "invoice calculation edge cases",
search_type: "CHUNKS"
});
// If complex reasoning needed
const deeper = await cognee.cognee_search({
search_query: "how does invoice tax calculation interact with discounts",
search_type: "GRAPH_COMPLETION"
});
await cognee.cognee_cognify({
data: `
## Decision: Use database triggers for invoice totals
**Problem:** Invoice totals getting out of sync with line items
**Solution:** Database triggers auto-calculate totals on line item changes
**Rationale:**
- Single source of truth
- No race conditions
- Works regardless of which app modifies data
**Files:**
- supabase/migrations/xxx_invoice_triggers.sql
- apps/web/src/features/invoices/hooks.ts
**Gotcha:** Never set total_amount directly - it's trigger-managed
`
});
await cognee.cognee_save_interaction({
data: `
Q: Why do invoice totals sometimes show stale values?
A: The balance field is calculated by a database trigger. If you're seeing
stale values, the trigger may not have fired yet due to transaction
isolation. Solution: Use RETURNING clause or refresh after commit.
`
});
// Run once per project to ingest CLAUDE.md, .context/, etc.
await cognee.cognee_cognee_add_developer_rules({ base_path: "." });
// Later, retrieve learned rules
const rules = await cognee.cognee_get_developer_rules({});
## [Type]: [Short Title]
**Problem:** What issue were we solving?
**Solution:** What did we decide/implement?
**Rationale:** Why this approach over alternatives?
**Files:** Which files were involved?
**Gotchas:** What to watch out for?
| Mistake | Why It's Wrong | Do This Instead |
|---|---|---|
| Always use GRAPH_COMPLETION | Wastes tokens on simple queries | Start with CHUNKS, escalate if needed |
| Skip search "to save time" | Miss critical prior decisions | Quick CHUNKS search is nearly free |
| Store everything | Noise drowns signal | Store only significant decisions |
| Forget to check status | Search incomplete graph | Always verify cognify_status |
| Store without structure | Hard to search later | Use consistent format template |
| Error | Cause | Solution |
|---|---|---|
| Empty search results | Graph not indexed yet | Check cognify_status, wait for completion |
cognify timeout | Large data payload | Batch into smaller chunks |
| CODE search returns nothing | Repo not indexed | Run codify first, check codify_status |
| Connection errors | MCP server issue | Retry after delay, check server status |
// After cognify, always verify before searching
const status = await cognee.cognee_cognify_status({});
// Status response structure:
// {
// "pipeline": "cognify_pipeline",
// "dataset": "main_dataset",
// "jobs": [
// { "status": "completed" | "running" | "failed", "progress": 0-100 }
// ]
// }
// Wait pattern for background operations
async function waitForCognify(maxAttempts = 10) {
for (let i = 0; i < maxAttempts; i++) {
const status = await cognee.cognee_cognify_status({});
if (status.includes("completed")) return true;
if (status.includes("failed")) throw new Error("Cognify failed");
await new Promise(r => setTimeout(r, 2000)); // Wait 2s
}
return false; // Timeout
}
// If search fails, proceed without context (but log it)
async function searchWithFallback(query: string) {
try {
return await cognee.cognee_search({
search_query: query,
search_type: "CHUNKS"
});
} catch (error) {
console.warn(`Memory search failed: ${error}. Proceeding without context.`);
return null;
}
}
| Skill | Integration |
|---|---|
@cognee-memory-api | Fallback when MCP fails, admin-only endpoints |
@database-operations | Store migration decisions, query patterns |
@execution-analyzer | Store implementation analysis for future reference |
@find-tools | Cognee tools in memory-knowledge category |
@systematic-debugging | Store root cause analyses |
If MCP cognee.* tools fail (timeout, connection error), use @cognee-memory-api for curl-based fallback via REST API at http://31.220.108.131:8001.