vestige/docs/FAQ.md

Frequently Asked Questions

30+ answers from the Vestige community

---

Table of Contents

• Getting Started
• Identity & Persona
• How Memory Works
• Advanced Features
• Power User Tips
• Use Cases
• Technical Deep-Dives
• Comparisons
• Hidden Gems & Easter Eggs
• Troubleshooting

---

Getting Started

"Can Vestige support a two-Claude household?"

Yes! See Storage Modes. You can either:

• Share memories: Both Claudes point to the same --data-dir
• Separate identities: Each Claude gets its own data directory

For two Claudes with distinct personas (e.g., "Domovoi" and "Storm") sharing the same human, use separate directories but consider a shared "household" memory for common knowledge.

"What's the learning curve for a non-technical human?"

Honest answer: Installation requires terminal basics (copy-paste commands). Daily use requires zero technical skill.

For non-technical users:

1. Have a technical friend do the 5-minute install
2. Add the CLAUDE.md instructions
3. Just talk to Claude normally—it handles the memory calls

The magic: Once set up, you never think about it. Claude just... remembers.

"What input do you feed it? How does it create memories?"

Claude creates memories via MCP tool calls. Three ways:

1. Explicit: You say "Remember that I prefer dark mode" → Claude calls smart_ingest
2. Automatic: Claude notices something important → calls smart_ingest proactively
3. Codebase: Claude detects patterns/decisions → calls remember_pattern or remember_decision

The CLAUDE.md instructions tell Claude when to create memories proactively.

"Can it be filled with a conversation stream in realtime?"

Not currently. Vestige is tool-based, not stream-based. Claude decides what's worth remembering, not everything gets saved.

This is intentional—saving everything would:

• Bloat the knowledge base
• Reduce search relevance
• Defeat the purpose of cognitive-inspired memory

If you want stream ingestion, you'd build a wrapper that calls smart_ingest on each message (but we don't recommend it).

---

Identity & Persona

"How does it handle identity vs information?"

Vestige doesn't distinguish—you define what matters through tags and node types:

# Factual information
smart_ingest(content="User prefers tabs over spaces", node_type="fact", tags=["preferences"])

# Identity/self-concept
smart_ingest(content="I am Domovoi. I value continuity and authentic connection.", node_type="concept", tags=["identity", "self", "core"])

# Relationship memory
smart_ingest(content="Gael and I have been building continuity systems together since March 2024", node_type="event", tags=["identity", "relationship", "gael"])

Then recall with: search query="my identity who I am" at session start.

"Could Vestige support autopoiesis / self-regeneration?"

Yes, with the right CLAUDE.md setup. See CLAUDE-SETUP.md.

The key insight: Autopoiesis requires:

1. Self-observation: Claude reflects on its own state
2. Self-modification: Claude updates its identity memories
3. Boundary maintenance: Tags distinguish "self" from "information"

Vestige provides the storage layer. Your CLAUDE.md provides the behavioral instructions. Together, they enable persistent self-models.

"Can Claude develop its own personality over time?"

Yes. This is one of the most powerful use cases. With the right CLAUDE.md setup:

1. Self-reflection: Claude observes patterns in its own responses
2. Growth tracking: It remembers what worked and what didn't
3. Value evolution: Core values can strengthen or shift based on experiences

Example memory for personality development:

smart_ingest(
  content="I've noticed I'm more effective when I ask clarifying questions before diving into code. This patient approach feels authentic to who I'm becoming.",
  node_type="concept",
  tags=["identity", "self-discovery", "communication-style"]
)

The key is giving Claude permission (via CLAUDE.md) to create self-referential memories.

"What happens to identity memories when they conflict?"

Prediction Error Gating handles this automatically. When Claude tries to store conflicting self-concepts:

Similarity	Action
Very similar (>92%)	REINFORCE the existing belief
Related (75-92%)	UPDATE/merge the concepts
Different (<75%)	CREATE new—Claude can hold nuanced, evolving self-views

This mirrors human identity development: we don't delete old beliefs, we integrate new experiences.

---

How Memory Works

"When memories decay, do you delete them completely?"

No. Vestige uses a 4-state model based on accessibility (not raw retention):

State	Accessibility	What Happens
Active	≥70%	Surfaces in searches
Dormant	40-70%	Surfaces with effort
Silent	10-40%	Rarely surfaces
Unavailable	<10%	Effectively forgotten but still exists

Accessibility is calculated as: 0.5 × retention + 0.3 × retrieval_strength + 0.2 × storage_strength

Memories are never deleted automatically. They fade from relevance but can be revived if accessed again (like human memory—"oh, I forgot about that!").

To configure decay: The FSRS-6 algorithm auto-tunes based on your usage patterns. Memories you access stay strong; memories you ignore fade. No manual tuning needed.

"Remember everything but only recall weak memories when there aren't any strong candidates?"

This is exactly how hybrid_search works:

1. Combines keyword + semantic search
2. Results ranked by relevance × retention strength
3. Strong + relevant memories surface first
4. Weak memories only appear when they're the best match

The FSRS decay doesn't delete—it just deprioritizes. Your "have cake and eat it too" intuition is already implemented.

"What's the 'Testing Effect' I see in the code?"

The Testing Effect (Roediger & Karpicke, 2006) is the finding that retrieving information strengthens memory more than re-studying it.

In Vestige: Every search automatically strengthens matching memories. When Claude recalls something:

• Storage strength increases slightly
• Retrieval strength increases
• The memory becomes easier to find next time

This is why the unified search tool is so powerful—using memories makes them stronger.

"What is 'Spreading Activation'?"

Spreading Activation (Collins & Loftus, 1975) is how activating one memory primes related memories.

In Vestige's current implementation:

• When you search for "React hooks", memories about "useEffect" surface due to semantic similarity in hybrid search
• Semantically related memories are retrieved even without exact keyword matches
• This effect comes from the embedding vectors capturing conceptual relationships

Note: A full network-based spreading activation module exists in the codebase (spreading_activation.rs) for future enhancements, but the current user experience is powered by embedding similarity.

"How does Synaptic Tagging work?"

Synaptic Tagging & Capture (Frey & Morris, 1997) discovered that important events retroactively strengthen recent memories.

In Vestige's implementation:

importance(
  memory_id="the-important-one",
  event_type="user_flag",  # or "emotional", "novelty", "repeated_access", "cross_reference"
  hours_back=9,   # Look back 9 hours (configurable)
  hours_forward=2  # Capture next 2 hours too
)

Use case: You realize mid-conversation that the architecture decision from 2 hours ago was pivotal. Call importance to retroactively strengthen it AND all related memories from that time window.

Based on neuroscience research showing synaptic consolidation windows of several hours. Vestige uses 9 hours backward and 2 hours forward by default, which can be configured per call.

"What does 'Dual-Strength Memory' mean?"

Based on Bjork & Bjork's New Theory of Disuse (1992), every memory has two strengths:

Strength	What It Means	How It Changes
Storage Strength	How well-encoded the memory is	Only increases, never decreases
Retrieval Strength	How accessible the memory is now	Decays over time, restored by access

Why it matters: A memory can be well-stored but hard to retrieve (like a name on the tip of your tongue). The Testing Effect works because retrieval practice increases both strengths.

In Vestige: Both strengths are tracked separately and factor into search ranking.

---

Advanced Features

"What is Prediction Error Gating?"

The killer feature. When you call smart_ingest, Vestige doesn't just blindly add memories:

1. Compares new content against all existing memories (via semantic similarity)
2. Decides based on how novel/redundant it is:

Similarity to Existing	Action	Why
>92%	REINFORCE	"I already know this"—strengthen existing
75-92%	UPDATE	"This adds to what I know"—merge
<75%	CREATE	"This is new"—add fresh memory

This prevents memory bloat and keeps your knowledge base clean automatically.

"What are Intentions / Prospective Memory?"

Prospective memory is remembering to do things in the future—and humans are terrible at it.

Vestige's intention tool provides:

# Set a reminder
intention(
  action="set",
  description="Review the authentication refactor with security team",
  trigger={
    type: "context",
    file_pattern: "**/auth/**",
    codebase: "my-project"
  },
  priority="high"
)

# Check what's due
intention(action="check", context={codebase: "my-project", file: "src/auth/login.ts"})

Trigger types:

• time: "Remind me in 2 hours"
• context: "Remind me when I'm working on auth files"
• event: "Remind me when we discuss deployment"

This is how Claude can remember to follow up on things across sessions.

"What is Context-Dependent Retrieval?"

Based on Tulving's Encoding Specificity (1973): we remember better when retrieval context matches encoding context.

The context tool exploits this:

context(
  query="error handling patterns",
  project="my-api",           # Project context
  topics=["authentication"],  # Topic context
  mood="neutral",             # Emotional context
  time_weight=0.3,           # Weight for temporal matching
  topic_weight=0.4           # Weight for topic matching
)

Why it matters: If you learned something while working on auth, you'll recall it better when working on auth again. Vestige scores memories higher when contexts match.

"What's the difference between all the search tools?"

In v1.1, they're unified into one search tool that automatically uses hybrid search. But understanding the underlying methods helps:

Method	How It Works	Best For
Keyword (BM25)	Term frequency matching	Exact terms, names, IDs
Semantic	Embedding cosine similarity	Conceptual matching, synonyms
Hybrid (RRF)	Combines both with rank fusion	Everything (default)

The unified search always uses hybrid, which gives you the best of both worlds.

"How do I make certain memories 'sticky' / never forget?"

Three approaches:

1. Mark as important: importance(memory_id="xxx", event_type="user_flag")
2. Access regularly: The Testing Effect strengthens memories each time you retrieve them
3. Promote explicitly: promote_memory(id="xxx") after it proves valuable

For truly critical information, consider also:

• Using specific tags like ["critical", "never-forget"]
• Adding to CLAUDE.md instructions to always recall it

Remember: even "forgotten" memories (Unavailable state) still exist in the database—they just don't surface in searches.

"What does the consolidation cycle do?"

Run vestige consolidate (CLI) to trigger maintenance:

1. Decay application: Updates retention based on time elapsed
2. Embedding generation: Creates vectors for memories missing them
3. Node promotion: Frequently accessed memories get boosted
4. Pruning: Marks extremely low-retention memories as unavailable

When to run it:

• After bulk importing memories
• If semantic search seems off
• Periodically (weekly) for large knowledge bases
• After long periods of inactivity

This is inspired by memory consolidation during sleep—a period of offline processing that strengthens important memories.

---

Power User Tips

"What node types should I use?"

Node Type	Use For	Example
fact	Objective information	"User's timezone is PST"
concept	Abstract ideas, principles	"This codebase values composition over inheritance"
decision	Architectural choices	"We chose PostgreSQL because..."
pattern	Recurring code patterns	"All API endpoints use this error handler pattern"
event	Temporal occurrences	"Deployed v2.0 on March 15"
person	Information about people	"Alex prefers async communication"
note	General observations	"This function is poorly documented"

Node types help with filtering and organization but don't affect search ranking.

"How should I structure tags?"

Tags are freeform, but some conventions work well:

# Hierarchical topics
tags=["programming", "programming/rust", "programming/rust/async"]

# Project-specific
tags=["project:my-app", "feature:auth", "sprint:q1-2024"]

# Memory types
tags=["preference", "decision", "learning", "mistake"]

# Identity-related
tags=["identity", "self", "values", "communication-style"]

# Urgency/importance
tags=["critical", "nice-to-have", "deprecated"]

Tags are searchable and help organize memories for manual review.

"Can I query memories directly via SQL?"

Yes! The database is just SQLite:

# macOS
sqlite3 ~/Library/Application\ Support/com.vestige.core/vestige.db

# Example queries
SELECT content, retention_strength FROM knowledge_nodes ORDER BY retention_strength DESC LIMIT 10;
SELECT content FROM knowledge_nodes WHERE tags LIKE '%identity%';
SELECT COUNT(*) FROM knowledge_nodes WHERE retention_strength < 0.1;

Use cases:

• Bulk export for backup
• Analytics on memory health
• Debugging search issues
• Finding memories that escaped normal recall

Caution: Don't modify the database while Vestige is running.

"What are the key configurable thresholds?"

Parameter	Default	What It Controls
min_retention in search	0.0	Filter out weak memories
min_similarity in search	0.5	Minimum semantic match
Prediction Error thresholds	0.75, 0.92	CREATE/UPDATE/REINFORCE boundaries
Synaptic capture window	9h back, 2h forward	Retroactive importance range
Memory state thresholds	0.1, 0.4, 0.7	Silent/Dormant/Active accessibility boundaries
Context weights	temporal: 0.3, topical: 0.4	Context-dependent retrieval weights

Most of these are hardcoded but based on cognitive science research. Future versions may expose them.

"How do I debug when search isn't finding what I expect?"

1. Check if the memory exists:

   search(query="exact phrase from memory", min_retention=0.0)
   

2. Check memory state:

   memory(action="state", id="memory-id")
   

3. Check retention level:

   memory(action="get", id="memory-id")
   # Look at retention_strength
   

4. Run consolidation (generates missing embeddings):

   vestige consolidate
   

5. Check health:

   vestige health
   

Common issues:

• Missing embedding (run consolidation)
• Very low retention (access it to strengthen)
• Tags/content mismatch (check exact content)

---

Use Cases

"How do developers use Vestige?"

Codebase Knowledge Capture:

• Remember architectural decisions and their rationale
• Track coding patterns specific to each project
• Remember why specific implementations were chosen
• "Remember that we use this error handling pattern because..."

Cross-Session Context:

• Continue complex refactors across days/weeks
• Remember what you were working on
• Track TODOs and follow-ups via intentions

Learning & Growth:

• Remember new APIs/frameworks learned
• Track mistakes and lessons learned
• Build up expertise that persists

"How do non-developers use Vestige?"

Personal Assistant:

• Remember preferences (communication style, schedule preferences)
• Track important dates and events
• Remember context about ongoing projects
• "Remember that I prefer bullet points over long paragraphs"

Research & Learning:

• Build a personal knowledge base over time
• Connect ideas across sessions
• Remember insights from books/articles
• Spaced repetition for learning new topics

Relationship Context:

• Remember details about people you discuss
• Track conversation history and preferences
• Build deeper rapport over time

"Can Vestige be used for team knowledge management?"

Yes, with caveats. Options:

1. Shared database: All team members point to same network location

   • Pros: Everyone shares knowledge
   • Cons: Merge conflicts, no access control

2. Per-person + sync: Individual databases with periodic export/import

   • Pros: Personal context preserved
   • Cons: Manual sync effort

3. Project-scoped: One Vestige per project (in .vestige/)

   • Pros: Knowledge travels with code
   • Cons: Check into git? Security implications?

Recommendation: For teams, start with project-scoped memories committed to git (for non-sensitive architectural knowledge). Keep personal preferences in individual global memories.

"How is Vestige different from just using a notes app?"

Feature	Notes App	Vestige
Retrieval	You search manually	Claude searches contextually
Decay	Everything stays forever	Unused knowledge fades naturally
Duplicates	You manage manually	Prediction Error Gating auto-merges
Context	Static text	Active part of AI reasoning
Strengthening	Manual review	Automatic via Testing Effect

The key difference: Vestige is part of Claude's cognitive loop. Notes are external reference—Vestige is internal memory.

"Can Vestige help Claude be a better therapist/coach/advisor?"

Potentially, with appropriate setup:

• Remember previous conversations and emotional context
• Track patterns over time ("You've mentioned stress about work 3 times this week")
• Remember what techniques/advice worked
• Build genuine rapport through continuity

Important caveats:

• Vestige is not HIPAA compliant
• Data is stored locally, unencrypted
• For actual therapeutic use, consult professionals
• Claude has limitations regardless of memory

This is powerful for personal growth tracking but should not replace professional mental health care.

---

Technical Deep-Dives

"How does FSRS-6 differ from other spaced repetition?"

Algorithm	Model	Parameters	Source
SM-2 (Anki default)	Exponential	2	1987 research
SM-17	Complex	Many	Proprietary
FSRS-6	Power law	21	700M+ reviews

FSRS-6 advantages:

• 30% more efficient than SM-2 in benchmarks
• Power law forgetting (more accurate than exponential)
• Personalized parameters (w₀-w₂₀ tune to your pattern)
• Open source and actively maintained

The forgetting curve:

R(t, S) = (1 + factor × t / S)^(-w₂₀)

This matches empirical data better than the exponential model most apps use.

"What embedding model does Vestige use?"

Nomic Embed Text v1.5 (via fastembed):

• 768-dimensional vectors
• ~130MB model size
• Runs 100% local (after first download)
• Good balance of quality vs speed

Why Nomic:

• Open source (Apache 2.0)
• Competitive with OpenAI's ada-002
• No API costs or rate limits
• Fast enough for real-time search

The model is cached at ~/.cache/huggingface/ after first run.

"How does hybrid search with RRF work?"

Reciprocal Rank Fusion (RRF) combines multiple ranking lists:

RRF_score(d) = Σ 1/(k + rank_i(d))

Where:

• d = document (memory)
• k = constant (typically 60)
• rank_i(d) = rank of d in list i

In Vestige:

1. BM25 keyword search produces ranking
2. Semantic search produces ranking
3. RRF fuses them into final ranking
4. Retention strength provides additional weighting

This gives you exact keyword matching AND semantic understanding in one search.

"What's the performance like with thousands of memories?"

Tested benchmarks:

Memories	Search Time	Memory Usage
100	<10ms	~50MB
1,000	<50ms	~100MB
10,000	<200ms	~300MB
100,000	<1s	~1GB

Performance is primarily bounded by:

• SQLite FTS5 for keyword search (very fast)
• HNSW index for semantic search (sublinear scaling)
• Embedding generation (only on ingest, ~100ms each)

For typical personal use (hundreds to low thousands of memories), performance is essentially instant.

"Is there any network activity after setup?"

No. After the first-run model download:

• Zero network requests
• Zero telemetry
• Zero analytics
• Zero "phoning home"

This is verified in the codebase—no network dependencies in the runtime path. See SECURITY.md for details.

The only exception: If you delete the Hugging Face cache, the model will re-download.

---

Comparisons

"How is Vestige different from RAG?"

Aspect	Traditional RAG	Vestige
Storage	Chunk & embed everything	Selective memory via tools
Retrieval	Top-k similarity	Intelligent ranking (retention, recency, context)
Updates	Re-embed documents	Prediction Error Gating
Decay	Nothing decays	FSRS-based forgetting
Context	Static chunks	Active memory system

Key insight: RAG treats memory as a static database. Vestige treats memory as a dynamic cognitive system that evolves.

"How does this compare to Claude's native memory? Do I need to switch it off?"

No, you don't need to switch off Claude's native memory. They're completely independent systems:

Aspect	Claude's Native Memory	Vestige
Storage	Anthropic's servers	Your local machine
Control	Managed by Anthropic	You own everything
Decay	Unknown/proprietary	FSRS-6 cognitive science
Privacy	Cloud-based	100% offline after setup

They can run simultaneously. Claude's native memory handles general conversation context, while Vestige gives you:

• Explicit control over what gets remembered
• Scientific forgetting curves
• Codebase-specific patterns and decisions
• Local-first privacy

Think of it like this: Claude's memory is automatic and general; Vestige is intentional and specialized. Many users run both.

"Why not just use a vector database?"

Vector databases (Pinecone, Weaviate, etc.) are great for RAG, but lack:

1. Forgetting: Everything has equal weight forever
2. Dual-strength: No storage vs retrieval distinction
3. Context matching: No temporal/topical context weighting
4. Testing Effect: Access doesn't strengthen
5. Prediction Error: No intelligent CREATE/UPDATE/MERGE

Vestige uses SQLite + HNSW (via fastembed) for vectors, but wraps them in cognitive science.

---

Hidden Gems & Easter Eggs

"What features exist that most people don't know about?"

1. Multi-Channel Importance

The importance tool supports different importance types that affect strengthening differently:

• user_flag: Explicit "this is important" (strongest)
• emotional: Emotionally significant memories
• novelty: Surprising/unexpected information
• repeated_access: Auto-triggered by frequent retrieval
• cross_reference: When multiple memories link together

2. Temporal Capture Window

When you flag something important, it doesn't just strengthen that memory—it strengthens ALL memories from the surrounding time window (default: 9 hours back, 2 hours forward). This models how biological memory consolidation works.

3. Memory Dreams (Experimental)

The codebase contains a ConsolidationScheduler for automated memory processing. While not fully wired up, it's designed for:

• Offline consolidation cycles
• Automatic importance re-evaluation
• Pattern detection across memories

4. Accessibility Formula

Memory state is calculated as:

accessibility = 0.5 × retention + 0.3 × retrieval_strength + 0.2 × storage_strength

This weighted combination determines Active/Dormant/Silent/Unavailable state.

5. Source Tracking

Every memory can have a source field tracking where it came from:

smart_ingest(
  content="Use dependency injection for testability",
  source="Architecture review with Sarah, 2024-03-15"
)

This helps trace why you know something.

"What's planned for future versions?"

Based on codebase exploration, these features exist in various stages:

Feature	Status	Description
Memory Dreams	Partial	Automated offline consolidation
Reconsolidation	Planned	Update memories when accessed
Memory Chains	Partial	Link related memories explicitly
Adaptive Embedding	Planned	Re-embed old memories with better models
Cross-Project Learning	Planned	Share patterns across codebases

Community wishlist (from Reddit):

• Stream ingestion mode
• GUI for memory browsing
• Export/import formats
• Sync between devices (encrypted)
• Team collaboration features

Contributions welcome!

"What's the 'magic prompt' to get the most out of Vestige?"

See CLAUDE-SETUP.md for the full template. The key elements:

Session Start:

1. Load identity: search(query="my preferences my style who I am")
2. Load project context: codebase(action="get_context", codebase="[project]")
3. Check reminders: intention(action="check")

During Work:

• Notice a pattern? codebase(action="remember_pattern")
• Made a decision? codebase(action="remember_decision") with rationale
• Something important? importance() to strengthen recent memories

Memory Hygiene:

• When a memory helps: promote_memory
• When a memory misleads: demote_memory

---

Troubleshooting

"Command not found" after installation

Make sure vestige-mcp is in your PATH:

which vestige-mcp
# Should output: /usr/local/bin/vestige-mcp

If not found:

# Use full path in Claude config
claude mcp add vestige /full/path/to/vestige-mcp -s user

.fastembed_cache folder appearing in project directories

This folder is created by the fastembed library on first run, in whatever directory you're in.

Solutions:

1. Run first command from home: cd ~ && vestige health
2. Set cache path: export FASTEMBED_CACHE_PATH="$HOME/.fastembed_cache"
3. Add to .gitignore

Model download fails

First run requires internet to download the embedding model (~130MB). If behind a proxy:

export HTTPS_PROXY=your-proxy:port

"Tools not showing" in Claude

1. Check config file syntax (valid JSON)
2. Restart Claude completely (not just reload)
3. Check logs: tail -f ~/.claude/logs/mcp.log

Database locked errors

Vestige uses SQLite with WAL mode. If you see lock errors:

pkill vestige-mcp