mirror of
https://github.com/samvallad33/vestige.git
synced 2026-04-25 00:36:22 +02:00
eb16d684fc
Previously, fastembed created .fastembed_cache in the current working directory, polluting project folders with symlinks. Now uses platform-appropriate cache directories: - macOS: ~/Library/Caches/com.vestige.core/fastembed - Linux: ~/.cache/vestige/fastembed - Windows: %LOCALAPPDATA%\vestige\cache\fastembed Can still be overridden with FASTEMBED_CACHE_PATH env var. Fixes user feedback about .fastembed_cache appearing in random folders. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
198 lines
5.2 KiB
Markdown
198 lines
5.2 KiB
Markdown
# Vestige
|
|
|
|
**Memory that fades like yours does.**
|
|
|
|
[](https://github.com/samvallad33/vestige)
|
|
[](https://github.com/samvallad33/vestige/releases/latest)
|
|
[](LICENSE)
|
|
[](https://modelcontextprotocol.io)
|
|
|
|
> The only MCP memory server built on cognitive science. FSRS-6 spaced repetition, spreading activation, synaptic tagging—all running 100% local.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### 1. Download
|
|
|
|
**macOS (Apple Silicon):**
|
|
```bash
|
|
curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-aarch64-apple-darwin.tar.gz | tar -xz
|
|
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/
|
|
```
|
|
|
|
<details>
|
|
<summary>Other platforms</summary>
|
|
|
|
**macOS (Intel):**
|
|
```bash
|
|
curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-x86_64-apple-darwin.tar.gz | tar -xz
|
|
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/
|
|
```
|
|
|
|
**Linux:**
|
|
```bash
|
|
curl -L https://github.com/samvallad33/vestige/releases/latest/download/vestige-mcp-x86_64-unknown-linux-gnu.tar.gz | tar -xz
|
|
sudo mv vestige-mcp vestige vestige-restore /usr/local/bin/
|
|
```
|
|
|
|
**Windows:** Download from [Releases](https://github.com/samvallad33/vestige/releases/latest)
|
|
|
|
**Build from source:**
|
|
```bash
|
|
git clone https://github.com/samvallad33/vestige && cd vestige
|
|
cargo build --release
|
|
sudo cp target/release/vestige-mcp /usr/local/bin/
|
|
```
|
|
</details>
|
|
|
|
### 2. Connect to Claude
|
|
|
|
```bash
|
|
claude mcp add vestige vestige-mcp -s user
|
|
```
|
|
|
|
### 3. Restart & Test
|
|
|
|
Restart Claude, then:
|
|
|
|
> "Remember that I prefer TypeScript over JavaScript"
|
|
|
|
New session:
|
|
|
|
> "What are my coding preferences?"
|
|
|
|
**It remembers.**
|
|
|
|
---
|
|
|
|
## Why Vestige?
|
|
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| AI forgets between sessions | Persistent memory with intelligent retrieval |
|
|
| RAG dumps irrelevant context | **Prediction Error Gating** auto-decides CREATE/UPDATE/SUPERSEDE |
|
|
| Memory bloat eats tokens | **FSRS-6 decay** naturally fades unused memories |
|
|
| No idea what AI "knows" | `search` tool lets you query anytime |
|
|
| Privacy concerns | **100% local** after initial setup |
|
|
|
|
---
|
|
|
|
## Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `search` | Unified search (keyword + semantic + hybrid) |
|
|
| `smart_ingest` | Intelligent ingestion with duplicate detection |
|
|
| `ingest` | Simple memory storage |
|
|
| `memory` | Get, delete, or check memory state |
|
|
| `codebase` | Remember patterns and architectural decisions |
|
|
| `intention` | Set reminders and future triggers |
|
|
| `promote_memory` | Mark memory as helpful (strengthens) |
|
|
| `demote_memory` | Mark memory as wrong (weakens) |
|
|
|
|
---
|
|
|
|
## Make Claude Use Vestige Automatically
|
|
|
|
Add this to your `CLAUDE.md`:
|
|
|
|
```markdown
|
|
## Vestige Memory System
|
|
|
|
At the start of every conversation, check Vestige for context:
|
|
1. Recall user preferences and instructions
|
|
2. Recall relevant project context
|
|
3. Operate in proactive memory mode - save important info without being asked
|
|
```
|
|
|
|
### Trigger Words
|
|
|
|
| User Says | Claude Does |
|
|
|-----------|-------------|
|
|
| "Remember this" | `smart_ingest` immediately |
|
|
| "I prefer..." / "I always..." | Save as preference |
|
|
| "Remind me..." | Create `intention` |
|
|
| "This is important" | `smart_ingest` + `promote_memory` |
|
|
|
|
[Full CLAUDE.md templates →](docs/CLAUDE-SETUP.md)
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
<details>
|
|
<summary>"Command not found" after installation</summary>
|
|
|
|
Ensure `vestige-mcp` is in PATH:
|
|
```bash
|
|
which vestige-mcp
|
|
```
|
|
|
|
Or use full path in Claude config:
|
|
```bash
|
|
claude mcp add vestige /full/path/to/vestige-mcp -s user
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Model cache location</summary>
|
|
|
|
The embedding model (~130MB) is cached in platform-specific directories:
|
|
- **macOS**: `~/Library/Caches/com.vestige.core/fastembed`
|
|
- **Linux**: `~/.cache/vestige/fastembed`
|
|
- **Windows**: `%LOCALAPPDATA%\vestige\cache\fastembed`
|
|
|
|
Override with: `export FASTEMBED_CACHE_PATH=/custom/path`
|
|
</details>
|
|
|
|
<details>
|
|
<summary>Model download fails</summary>
|
|
|
|
First run requires internet (~130MB). If behind proxy:
|
|
```bash
|
|
export HTTPS_PROXY=your-proxy:port
|
|
```
|
|
</details>
|
|
|
|
[More troubleshooting →](docs/FAQ.md#troubleshooting)
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
| Document | Contents |
|
|
|----------|----------|
|
|
| [FAQ](docs/FAQ.md) | 30+ answers to common questions |
|
|
| [How It Works](docs/SCIENCE.md) | FSRS-6, dual-strength memory, the neuroscience |
|
|
| [Storage Modes](docs/STORAGE.md) | Global, per-project, multi-Claude setup |
|
|
| [CLAUDE.md Setup](docs/CLAUDE-SETUP.md) | Templates for proactive memory use |
|
|
| [Configuration](docs/CONFIGURATION.md) | CLI commands, environment variables |
|
|
| [Changelog](CHANGELOG.md) | Version history |
|
|
|
|
---
|
|
|
|
## CLI Commands
|
|
|
|
```bash
|
|
vestige stats # Memory statistics
|
|
vestige health # System health check
|
|
vestige consolidate # Run memory maintenance
|
|
vestige restore <file> # Restore from backup
|
|
```
|
|
|
|
---
|
|
|
|
## Contributing
|
|
|
|
Issues and PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0 (dual-licensed)
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<i>Built by <a href="https://github.com/samvallad33">@samvallad33</a></i>
|
|
</p>
|