> **Transparency**: The ✅ features closely follow published algorithms. The ⚡ features are engineering heuristics *inspired by* the research—useful approximations, not literal neuroscience. We believe in honest marketing.
vestige stats --states # Cognitive state distribution
vestige health # System health check
vestige consolidate # Run memory maintenance
vestige restore <file> # Restore from backup
```
---
## FAQ (From the Community)
### Getting Started
<details>
<summary><b>"Can Vestige support a two-Claude household?"</b></summary>
**Yes!** See [Multi-Claude Household](#option-3-multi-claude-household) above. 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.
</details>
<details>
<summary><b>"What's the learning curve for a non-technical human?"</b></summary>
**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 above
3. Just talk to Claude normally—it handles the memory calls
**The magic**: Once set up, you never think about it. Claude just... remembers.
</details>
<details>
<summary><b>"What input do you feed it? How does it create memories?"</b></summary>
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 above tell Claude when to create memories proactively.
</details>
<details>
<summary><b>"Can it be filled with a conversation stream in realtime?"</b></summary>
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).
</details>
---
### Identity & Persona
<details>
<summary><b>"How does it handle identity vs information?"</b></summary>
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: `recall query="my identity who I am"` at session start.
</details>
<details>
<summary><b>"Could Vestige support autopoiesis / self-regeneration?"</b></summary>
**Yes, with the right CLAUDE.md setup.** See [Advanced Setup (Identity + Autopoiesis)](#advanced-setup-identity--autopoiesis) above.
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.
</details>
<details>
<summary><b>"Can Claude develop its own personality over time?"</b></summary>
**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.",
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.
</details>
<details>
<summary><b>"Remember everything but only recall weak memories when there aren't any strong candidates?"</b></summary>
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.
</details>
<details>
<summary><b>"What's the 'Testing Effect' I see in the code?"</b></summary>
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.
</details>
<details>
<summary><b>"What is 'Spreading Activation'?"</b></summary>
**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.*
</details>
<details>
<summary><b>"How does Synaptic Tagging work?"</b></summary>
**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.*
</details>
<details>
<summary><b>"What does 'Dual-Strength Memory' mean?"</b></summary>
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.
</details>
---
### Advanced Features
<details>
<summary><b>"What is Prediction Error Gating?"</b></summary>
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)
-`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.
</details>
<details>
<summary><b>"What is Context-Dependent Retrieval?"</b></summary>
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.
</details>
<details>
<summary><b>"What's the difference between all the search tools?"</b></summary>
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 |
- "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
</details>
<details>
<summary><b>"Can Vestige be used for team knowledge management?"</b></summary>
**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.
</details>
<details>
<summary><b>"How is Vestige different from just using a notes app?"</b></summary>
| Feature | Notes App | Vestige |
|---------|-----------|---------|
| Retrieval | You search manually | Claude searches contextually |
<summary><b>"Why not just use a vector database?"</b></summary>
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.
</details>
---
### Hidden Gems & Easter Eggs
<details>
<summary><b>"What features exist that most people don't know about?"</b></summary>
**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:
