Cognee Memory Skill

Triggers: 'remember this', 'what do you know about', 'knowledge graph', 'store decision', 'search memory', 'prior decisions', 'past solutions', 'what did we decide', 'save for future', 'recall context', 'what we learned', 'architectural decision', 'why did we choose'

Persistent 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 MCP call_tool_chain for direct graph operations. These are intentionally separate - hooks avoid API calls during git operations.

When NOT to Use This Skill

Skip loading this skill for:

• Simple file edits (typos, formatting, renaming)
• Questions answerable from current codebase search
• Work with no architectural or decision-making component
• Pure code generation without design decisions

---

Slash Commands

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

---

Automation Strategy: "Safety Net" Hybrid

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

Layer 1: Safety Net (SessionEnd Hook)

• Every non-trivial session transcript saved to ~/.cognee-memory/sessions/
• NOT indexed into graph (avoids pollution)
• Can be imported later via /mem-import

Layer 2: Deterministic Triggers (Git Hook)

• High-signal commits saved to ~/.cognee-memory/commits/
• Triggers on: fix:, feat:, refactor:, BREAKING, PR merges
• Skips trivial commits (typos, deps, formatting)
• Import via /mem-import

Layer 3: Explicit Curation (Slash Commands)

• Use commands above to manually curate high-value insights

---

MCP Usage (CRITICAL)

Always 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({});

---

When to Use Memory

DO Search (/mem-search) When:

• Starting work on unfamiliar code area
• Debugging an issue that feels familiar
• Making architectural decisions
• User asks "what did we decide about X"

DO Save (/mem-save) When:

• Made a significant architectural decision
• Fixed a non-obvious bug (root cause worth remembering)
• Discovered a gotcha or edge case
• Established a new pattern

DON'T Bother When:

• Trivial changes (typos, formatting)
• Simple lookups or questions
• Work already documented in code/docs

---

Search Type Decision Tree

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)

Quick Reference

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

---

Essential Tools (MCP via 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.

---

Token Optimization Strategies

1. Search Type Escalation (Default Strategy)

Start with CHUNKS (free)
    → If insufficient, try SUMMARIES
    → If still need more, use GRAPH_COMPLETION

2. Skip Search Entirely

When to skip:

• Typo fixes
• Single-line changes
• Documentation updates
• Formatting changes

3. Batch Operations

// 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]
  `
});

4. Check Status Before Search

// After adding new data, verify processing complete
const status = await cognee.cognee_cognify_status({});
// Only search if status shows completion

5. Cache Results (Same Session)

Don't re-search for the same query within a session. Reference prior results.

---

Code Examples (MCP)

Search Before Coding

// 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"
});

Store Decision After Work

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
  `
});

Log Q&A Interaction

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.
  `
});

Bootstrap Project Rules

// 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({});

---

What to Store (Memory Content Guide)

ALWAYS Store

• Architectural decisions with rationale
• Bug fixes with root cause analysis
• Gotchas and edge cases discovered
• Pattern choices (why X over Y)
• Integration decisions

Format Template

## [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?

DON'T Store

• Trivial changes (typos, formatting)
• Temporary debugging code
• Personal preferences without technical merit
• Information already in docs/comments

---

Anti-Patterns

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 Handling

Common Errors and Solutions

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

Checking Operation 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
}

Graceful Degradation

// 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;
  }
}

---

Red Flags - STOP and Review

• About to make architectural decision without searching prior context
• Debugging same issue you've seen before
• Implementing pattern without checking existing examples
• Making decision that contradicts stored rationale

---

Integration with Other Skills

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

MCP Failure Fallback

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.

---

References

• Search Types Guide
• Token Optimization
• Tool Reference
• Session Start Checklist
• Session End Checklist
• Workflow Examples