Vector Memory

Long-term memory that persists across sessions. Store facts, decisions, lessons, preferences — recall them later via semantic search.

Vector memory is a retrieval layer, not a source of truth. Files and code are the source of truth; vector memory helps you find relevant context fast.

References

• tools-reference.md — All MCP tools with full parameter docs
• retrieval-internals.md — Hybrid pipeline, Weibull decay model (load when debugging retrieval)

When to Store

When NOT to Store

• Temporary task state (use files)
• Things already in committed code or docs
• Conversation summaries ("today we discussed X") — store the extracted knowledge, not the summary
• Obvious facts the user can easily re-state

Memory Hygiene

1. Short and atomic — Each memory < 500 chars, one concept per memory
2. No conversation summaries — Store distilled knowledge, not "we talked about X"
3. Check before storing — memory_recall first to avoid duplicates
4. Accurate categories — Category affects retrieval quality; pick the right one

Mandatory Trigger Points

Recall Before Retry

When a tool fails or you encounter an error, search memory before retrying. You may have solved this exact problem before:

memory_recall(query: "npm install native module EPERM Windows")

This one habit prevents repeating the same mistakes across sessions.

Dual-Layer Storage (Lessons)

Every mistake or lesson learned gets stored twice:

# Layer 1: Technical fact (what happened)
memory_store(
  text: "npm publish with noEmit: true ships no dist/ — bin entry fails in npx",
  category: "fact",
  importance: 0.8
)

# Layer 2: Actionable rule (what to do next time)
memory_store(
  text: "Always build to dist/ before npm publish, never rely on runtime transpilers for published packages",
  category: "lesson",
  importance: 0.9,
  lesson_trigger: "publishing npm packages with TypeScript",
  lesson_rule: "always build to dist/ before publish",
  lesson_principle: "published packages must be self-contained"
)

Why two? Different queries find different layers. "Why did publish fail?" hits the fact. "How should I publish TypeScript?" hits the lesson.

Category Reference

Importance Scale

Confidence-Based Tiering

The Category Reference above gives default importance values. Adjust based on how confident the memory is:

Rule of thumb: How many times has this come up?

• Mentioned 3+ times → core
• Verified through implementation → working
• Mentioned once, still discussing → peripheral

Scopes

Memories can be scoped for multi-agent or multi-project setups:

memory_store(text: "...", scope: "project:acme")
memory_recall(query: "...", scope: "project:acme")

Quick Reference

Store

memory_store(text: "...", category: "fact", importance: 0.7)

Recall

memory_recall(query: "database migration strategy", category: "decision", limit: 5)

Good queries describe the situation, not the exact stored text. Vector search finds semantic matches.

Update

memory_update(memoryId: "a0e8d0fb", text: "Updated: now using OAuth 2.1")

For preference and entity, text changes create a new version (supersede) — history is preserved.

Merge

memory_merge(primaryId: "a0e8d0fb", secondaryId: "3c31e862", mergedText: "Combined memory")

Forget

memory_forget(memoryId: "a0e8d0fb")
memory_forget(query: "outdated migration plan")

History

memory_history(memoryId: "a0e8d0fb", direction: "both")

Setup

Requires @cablate/memory-lancedb-mcp — see mcp.example.json for configuration.