Vector memory

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

Signal	Category	Example
User states a preference	preference	"I prefer tabs over spaces"
A fact is established	fact	"The API uses OAuth 2.0 with PKCE"
A decision is made with rationale	decision	"Chose PostgreSQL over MongoDB because..."
A mistake was made and corrected	lesson	"CSS not applying → check for syntax errors above"
An important entity is introduced	entity	"Acme Corp is the client, contact: [email protected]"
A reusable technique is learned	skill	"Remotion animations use interpolate()"

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

When	Action
Session start	memory_recall with keywords from user's first message
After a decision	memory_store with category decision
After a mistake	memory_store × 2 — dual-layer (see below)
Tool fails / error occurs	memory_recall first — you may have hit this before
Session end	Review: any new facts, decisions, or lessons worth persisting?

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

Meaning	Category	Importance	Typical use
User preference	preference	0.8	"I prefer TypeScript"
Objective fact	fact	0.7–0.8	"The API uses LanceDB for vector storage"
Decision with rationale	decision	0.85	"Chose LanceDB because it's embedded, no server needed"
Entity info	entity	0.7	"DeepInfra is the embedding provider"
Technique or method	skill	0.8	"Use interpolate() for Remotion animations"
Lesson from mistakes	lesson	0.85–0.9	With trigger/rule/principle fields
Other	other	0.5–0.7	Doesn't fit above categories

Importance Scale

Score	When
0.3–0.5	Nice to know, low impact
0.5–0.7	Useful context (default: 0.7)
0.7–0.85	Important decision or recurring pattern
0.85–1.0	Critical — wrong action has serious consequences

Confidence-Based Tiering

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

Confidence	Importance	Tier	When to use
Explicitly stated	0.9	core	User directly said "I want X", team decision, preference confirmed multiple times
Verified in practice	0.7–0.8	working	Learned from a mistake, technical fact verified by implementation
Exploratory	0.4–0.5	peripheral	One-time question, hypothesis under discussion, unconfirmed direction

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:

Format	Use case
global	Shared across all agents/projects
agent:<id>	Agent-private (default)
project:<id>	Project-scoped
user:<id>	User-scoped

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.