mirror of
https://github.com/samvallad33/vestige.git
synced 2026-06-22 21:28:08 +02:00
Release v2.1.1 portable sync
This commit is contained in:
Sam Valladares
parent
738e4f7dce
commit
f3d63af12e
35 changed files with 3257 additions and 421 deletions
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**Vestige's defense-in-depth safety architecture for Claude Code.**
|
||||
|
||||
The Cognitive Sandwich wraps every Claude Code response in two layers of cognitive scaffolding:
|
||||
The default Cognitive Sandwich installer only stages files and removes old v2.1.0 hook wiring. It activates no Claude Code hooks and makes no automatic model calls. Both the preflight layer and the Stop-hook layer are explicit opt-ins:
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────┐
|
||||
|
|
@ -15,32 +15,31 @@ The Cognitive Sandwich wraps every Claude Code response in two layers of cogniti
|
|||
├────────────────────────────────────────────────┤
|
||||
│ 🥩 MEAT — Claude Code reasons │
|
||||
├────────────────────────────────────────────────┤
|
||||
│ 🥪 BOTTOM BREAD — Stop hooks │
|
||||
│ • Veto-detector (fast 50ms regex pre-screen) │
|
||||
│ • Sanhedrin Executioner (LOCAL Qwen3.6-35B) │
|
||||
│ • Synthesis stop validator (hedge detector) │
|
||||
│ 🥪 OPTIONAL BOTTOM BREAD — Stop hooks │
|
||||
│ • Veto-detector / synthesis validator │
|
||||
│ • Sanhedrin Executioner verifier │
|
||||
└────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
The Sanhedrin Executioner is the headline of v2.1.0. As of v2.1.0 it runs entirely on a local MLX model (`mlx-community/Qwen3.6-35B-A3B-4bit`), replacing the v2.0.x Haiku 4.5 subagent. **Zero API cost per Claude turn, fully offline, ~5–15s verdict latency on M-series Apple Silicon.**
|
||||
Sanhedrin, preflight, and all Vestige Claude Code hooks are optional. The default installer wires none of them; it does not call Claude, start MLX, require a 19 GB model download, or require 20+ GB of RAM. Users who want preflight context can opt in with `--enable-preflight`. Users who want the post-response verifier can opt in with `--enable-sanhedrin` and point it at any OpenAI-compatible `/v1/chat/completions` endpoint. On Apple Silicon, an additional `--with-launchd` flag can auto-start the local MLX Qwen backend.
|
||||
|
||||
---
|
||||
|
||||
## How a single response flows through the Sandwich
|
||||
|
||||
1. **You type a prompt in Claude Code.**
|
||||
2. **UserPromptSubmit hooks fire in parallel** (none can block — all fail-open):
|
||||
2. **If explicitly enabled, UserPromptSubmit hooks fire in parallel** (none can block — all fail-open):
|
||||
- `load-all-memory.sh` (opt-in) — dumps every memory MD into context
|
||||
- `synthesis-preflight.sh` — POSTs your prompt to `vestige-mcp` `/api/deep_reference`, injects the trust-scored reasoning chain
|
||||
- `cwd-state-injector.sh` — captures git status, branch, open PRs/issues, modified files
|
||||
- `vestige-pulse-daemon.sh` — injects fresh Vestige dream insights from the past 20 min into the next prompt context
|
||||
- `preflight-swarm.sh` — spawns the `lateral-thinker` subagent in fresh context to surface cross-disciplinary structural parallels
|
||||
3. **Claude reads the assembled context and generates a draft.**
|
||||
4. **Stop hooks fire serially** (any can VETO with `exit 2`, forcing a rewrite):
|
||||
4. **By default, no Vestige Stop hooks are installed.** If explicitly enabled, Stop hooks fire serially (any can VETO with `exit 2`, forcing a rewrite):
|
||||
- `veto-detector.sh` — fast regex against `veto`-tagged Vestige memories (~50ms)
|
||||
- `sanhedrin.sh` → `sanhedrin-local.py` — single-shot local Qwen3.6-35B-A3B verdict
|
||||
- `sanhedrin.sh` → `sanhedrin-local.py` — optional single-shot semantic verdict
|
||||
- `synthesis-stop-validator.sh` — regex against forbidden patterns (hedging, summary-instead-of-composition)
|
||||
5. **If all 3 Stop hooks return `exit 0`, the response is delivered.**
|
||||
5. **If all enabled Stop hooks return `exit 0`, the response is delivered.**
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -73,7 +72,7 @@ False-positive guards (added v2.1.0 after dogfood):
|
|||
### One-liner
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/samvallad33/vestige/v2.1.0/scripts/install-sandwich.sh | sh
|
||||
curl -fsSL https://raw.githubusercontent.com/samvallad33/vestige/v2.1.1/scripts/install-sandwich.sh | sh
|
||||
```
|
||||
|
||||
### From a checkout
|
||||
|
|
@ -82,30 +81,65 @@ curl -fsSL https://raw.githubusercontent.com/samvallad33/vestige/v2.1.0/scripts/
|
|||
git clone https://github.com/samvallad33/vestige
|
||||
cd vestige
|
||||
./scripts/install-sandwich.sh # add --force to overwrite existing hooks
|
||||
./scripts/check-sandwich-prereqs.sh # verify everything's wired
|
||||
./scripts/check-sandwich-prereqs.sh # verify no Vestige hooks are wired by default
|
||||
```
|
||||
|
||||
The default command does not activate any Claude Code hook. It removes old v2.1.0 Vestige hook wiring from `~/.claude/settings.json` while preserving unrelated user hooks.
|
||||
|
||||
### Optional Preflight
|
||||
|
||||
Preflight is a separate opt-in layer. It includes `preflight-swarm.sh`, which uses `claude -p --model claude-haiku-4-5-20251001`; it is not wired by default.
|
||||
|
||||
```bash
|
||||
./scripts/install-sandwich.sh --enable-preflight
|
||||
./scripts/check-sandwich-prereqs.sh --preflight
|
||||
```
|
||||
|
||||
### Optional Sanhedrin
|
||||
|
||||
Sanhedrin is a separate opt-in layer.
|
||||
|
||||
```bash
|
||||
# Wire the Sanhedrin Stop hook, using the default OpenAI-compatible endpoint.
|
||||
./scripts/install-sandwich.sh --enable-sanhedrin
|
||||
|
||||
# Apple Silicon only, and only if the machine has enough memory:
|
||||
./scripts/install-sandwich.sh --enable-sanhedrin --with-launchd
|
||||
|
||||
# x86 / Linux / Intel Mac: use any OpenAI-compatible endpoint.
|
||||
./scripts/install-sandwich.sh \
|
||||
--enable-sanhedrin \
|
||||
--sanhedrin-endpoint=http://127.0.0.1:11434/v1/chat/completions \
|
||||
--sanhedrin-model=qwen2.5:14b
|
||||
```
|
||||
|
||||
### Prerequisites
|
||||
|
||||
| Tool | Install |
|
||||
|---|---|
|
||||
| macOS Apple Silicon (M1+) | required for MLX |
|
||||
| Python 3.10+ | typically preinstalled |
|
||||
| `jq` | `brew install jq` |
|
||||
| `vestige-mcp` | `cargo install vestige-mcp` |
|
||||
| Claude Code | https://claude.ai/code |
|
||||
|
||||
Optional Apple Silicon local Sanhedrin backend:
|
||||
|
||||
| Tool | Install |
|
||||
|---|---|
|
||||
| macOS Apple Silicon (M1+) | required for MLX launchd only |
|
||||
| `uv` | `brew install uv` |
|
||||
| `mlx-lm` | `uv tool install mlx-lm` |
|
||||
| `huggingface_hub[cli]` | `uv tool install 'huggingface_hub[cli]'` |
|
||||
| `vestige-mcp` | `cargo install vestige-mcp` |
|
||||
| Claude Code | https://claude.ai/code |
|
||||
| Qwen3.6-35B-A3B-4bit | `hf download mlx-community/Qwen3.6-35B-A3B-4bit` (~19 GB) |
|
||||
|
||||
### What the installer does
|
||||
|
||||
1. Verifies prereqs (warnings for missing tools, fatal only on jq/python3).
|
||||
2. Copies hooks to `~/.claude/hooks/`, agents to `~/.claude/agents/`.
|
||||
3. Renders `launchd/com.vestige.mlx-server.plist.template` with your `$HOME` and chosen model, writes to `~/Library/LaunchAgents/`.
|
||||
4. `launchctl load` the plist (auto-start mlx_lm.server with the Qwen model on boot).
|
||||
5. Backs up existing `~/.claude/settings.json` to `.bak.pre-sandwich`, then `jq`-merges the hooks block.
|
||||
3. Backs up existing `~/.claude/settings.json` to `.bak.pre-sandwich`, then removes old Vestige hook wiring from previous v2.1.0 installs.
|
||||
4. With `--enable-preflight`, merges the UserPromptSubmit hooks block.
|
||||
5. With `--enable-sanhedrin`, writes `~/.claude/hooks/vestige-sanhedrin.env` and merges a Sanhedrin-enabled Stop hooks block.
|
||||
6. With `--enable-sanhedrin --with-launchd` on Apple Silicon, renders and loads `launchd/com.vestige.mlx-server.plist.template`.
|
||||
|
||||
### Uninstall
|
||||
|
||||
|
|
@ -120,7 +154,7 @@ cp ~/.claude/settings.json.bak.pre-sandwich ~/.claude/settings.json
|
|||
|
||||
## Performance notes
|
||||
|
||||
On M3 Max 16-core (400 GB/s memory bandwidth):
|
||||
Optional local MLX backend on M3 Max 16-core (400 GB/s memory bandwidth):
|
||||
- Sanhedrin verdict: 5–15 seconds end-to-end (single deep_reference + single Qwen call)
|
||||
- mlx_lm.server token generation: ~82 tok/s
|
||||
- mlx_lm.server peak resident memory: ~19.7 GB
|
||||
|
|
@ -134,11 +168,12 @@ On M3 Max 14-core or M2/M1 Max: closer to 3–7s prompt processing, ~50–60 tok
|
|||
|
||||
| Env var | Default | Effect |
|
||||
|---|---|---|
|
||||
| `VESTIGE_SANHEDRIN_ENABLED` | `1` | Set to `0` to disable Sanhedrin Stop hook entirely |
|
||||
| `VESTIGE_SANHEDRIN_ENABLED` | `0` | Set to `1` to enable the optional Sanhedrin Stop hook |
|
||||
| `VESTIGE_SWARM_ENABLED` | `1` | Set to `0` to disable preflight lateral-thinker swarm |
|
||||
| `VESTIGE_DASHBOARD_PORT` | `3927` | Vestige MCP HTTP API port used by hooks |
|
||||
| `MLX_ENDPOINT` | `http://127.0.0.1:8080/v1/chat/completions` | OpenAI-compatible chat completions endpoint for Sanhedrin |
|
||||
| `VESTIGE_SANDWICH_MODEL` | `mlx-community/Qwen3.6-35B-A3B-4bit` | Model launchd serves and Sanhedrin requests |
|
||||
| `VESTIGE_SANHEDRIN_ENDPOINT` | `http://127.0.0.1:8080/v1/chat/completions` | OpenAI-compatible chat completions endpoint for Sanhedrin |
|
||||
| `VESTIGE_SANHEDRIN_MODEL` | `mlx-community/Qwen3.6-35B-A3B-4bit` | Model name sent to the Sanhedrin endpoint |
|
||||
| `MLX_ENDPOINT` / `VESTIGE_SANDWICH_MODEL` | legacy aliases | Backward-compatible names still read by the bridge |
|
||||
| `VESTIGE_MEMORY_DIR` | (auto) | Override per-user Claude memory dir |
|
||||
|
||||
---
|
||||
|
|
@ -151,11 +186,12 @@ Full architecture memory: search Vestige for `god-tier-plan` or `cognitive-sandw
|
|||
|
||||
---
|
||||
|
||||
## Linux / Intel Mac
|
||||
## Linux / Intel Mac / x86
|
||||
|
||||
The launchd layer is macOS-arm64-only. On Linux or Intel Mac:
|
||||
- Hooks + agents install fine with `--no-launchd`
|
||||
- The Sanhedrin Stop hook will fail-open (mlx-server unreachable → exit 0)
|
||||
- Optional: run a remote mlx_lm.server / vLLM / Ollama OpenAI-compatible endpoint and set `MLX_ENDPOINT` to its `/v1/chat/completions` URL
|
||||
The base hook harness runs on x86. The launchd MLX helper is macOS-arm64-only.
|
||||
|
||||
Future v2.2.0 will add Linux-native MLX equivalents.
|
||||
On Linux, Windows under WSL, or Intel Mac:
|
||||
- Run `scripts/install-sandwich.sh` normally to stage files and remove old Vestige hook wiring. No hooks are activated.
|
||||
- If you want Sanhedrin, run an OpenAI-compatible endpoint such as vLLM, Ollama, llama.cpp server, or a remote MLX/vLLM box.
|
||||
- Install with `--enable-sanhedrin --sanhedrin-endpoint=<url> --sanhedrin-model=<model>`.
|
||||
- If the endpoint is unreachable, Sanhedrin fails open and does not block Claude Code.
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
## First-Run Network Requirement
|
||||
|
||||
Vestige downloads the **Nomic Embed Text v1.5** model (~130MB) from Hugging Face on first use.
|
||||
Vestige downloads the **Nomic Embed Text v1.5** model (~130MB) from Hugging Face on first use. Qwen3 embeddings are opt-in and download their own Hugging Face model when selected.
|
||||
|
||||
**All subsequent runs are fully offline.**
|
||||
|
||||
|
|
@ -25,6 +25,8 @@ Override with environment variable:
|
|||
export FASTEMBED_CACHE_PATH="/custom/path"
|
||||
```
|
||||
|
||||
Qwen3 currently uses Hugging Face Hub's Candle loader directly, so use the standard Hugging Face cache environment such as `HF_HOME` if you need to relocate that larger model cache.
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
|
@ -32,6 +34,7 @@ export FASTEMBED_CACHE_PATH="/custom/path"
|
|||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `VESTIGE_DATA_DIR` | OS per-user data directory | Storage directory fallback; overridden by `--data-dir`; database lives at `<dir>/vestige.db` |
|
||||
| `VESTIGE_EMBEDDING_MODEL` | `nomic-v1.5` | Embedding backend selector. Use `qwen3-0.6b` with a build that enables `qwen3-embeddings` |
|
||||
| `RUST_LOG` | `info` (via tracing-subscriber) | Log verbosity + per-module filtering |
|
||||
| `FASTEMBED_CACHE_PATH` | `./.fastembed_cache` | Embedding model cache location |
|
||||
| `VESTIGE_DASHBOARD_PORT` | `3927` | Dashboard HTTP + WebSocket port |
|
||||
|
|
@ -50,6 +53,7 @@ export FASTEMBED_CACHE_PATH="/custom/path"
|
|||
```bash
|
||||
vestige-mcp --data-dir /custom/path # Custom storage location
|
||||
VESTIGE_DATA_DIR=~/.vestige vestige-mcp # Env fallback storage location
|
||||
VESTIGE_DATA_DIR=./.vestige vestige stats # Point the CLI at the same custom DB
|
||||
vestige-mcp --help # Show all options
|
||||
```
|
||||
|
||||
|
|
@ -66,6 +70,10 @@ vestige stats --states # Cognitive state distribution
|
|||
vestige health # System health check
|
||||
vestige consolidate # Run memory maintenance
|
||||
vestige restore <file> # Restore from backup
|
||||
vestige portable-export <file> # Exact Vestige-to-Vestige archive
|
||||
vestige portable-import <file> # Import exact archive into an empty database
|
||||
vestige portable-import <file> --merge # Merge exact archive into this database
|
||||
vestige sync <file> # Pull/merge/push through a file backend
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -169,7 +177,7 @@ vestige update
|
|||
|
||||
**Pin to specific version:**
|
||||
```bash
|
||||
vestige update --version v2.1.0
|
||||
vestige update --version v2.1.1
|
||||
```
|
||||
|
||||
**Check your version:**
|
||||
|
|
|
|||
|
|
@ -24,6 +24,44 @@ Override precedence:
|
|||
|
||||
---
|
||||
|
||||
## Moving Memories Between Devices
|
||||
|
||||
For device-to-device migration, use a portable archive instead of the normal JSON export:
|
||||
|
||||
```bash
|
||||
# On the source machine
|
||||
vestige portable-export ~/Desktop/vestige-portable.json
|
||||
|
||||
# On the destination machine, before adding memories
|
||||
vestige portable-import ~/Desktop/vestige-portable.json
|
||||
```
|
||||
|
||||
Portable archives preserve raw Vestige storage rows: memory IDs, FSRS state, graph connections, suppression state, timestamps, audit history, and embedding blobs.
|
||||
|
||||
For one-time migration, keep the conservative empty-database import:
|
||||
|
||||
```bash
|
||||
vestige portable-import ~/Desktop/vestige-portable.json
|
||||
```
|
||||
|
||||
For cross-device sync, use merge mode or the file-backed sync command:
|
||||
|
||||
```bash
|
||||
# Merge a portable archive into an existing database.
|
||||
vestige portable-import ~/Dropbox/vestige/portable.json --merge
|
||||
|
||||
# Pull, merge, and push through a shared archive file.
|
||||
vestige sync ~/Dropbox/vestige/portable.json
|
||||
```
|
||||
|
||||
`vestige sync` uses the same pluggable portable-sync backend interface as the core library. v2.1.1 ships a file backend, which works with Dropbox, iCloud Drive, Syncthing, Git, network shares, or any folder-sync system. The merge algorithm applies delete tombstones, keeps newer local memories on timestamp conflicts, preserves stable IDs, rebuilds FTS after import, and writes the pushed archive atomically when the filesystem supports rename.
|
||||
|
||||
When using the MCP `export` tool with `format: "portable"`, Vestige writes the archive under the active data directory's `exports/` folder. The MCP `restore` tool only reads from that `exports/` or `backups/` folder by default; pass `allowAnyPath: true` only for a trusted local file you selected manually.
|
||||
|
||||
The regular `vestige export` / `vestige restore` path remains useful for human-readable backups, partial exports, and older files, but it re-ingests memory content and does not preserve every storage-level relationship.
|
||||
|
||||
---
|
||||
|
||||
## Storage Modes
|
||||
|
||||
### Option 1: Global Memory (Default)
|
||||
|
|
@ -69,6 +107,13 @@ This creates `.vestige/vestige.db` in your project root. Add `.vestige/` to `.gi
|
|||
|
||||
If both `VESTIGE_DATA_DIR` and `--data-dir` are set, the CLI flag wins. Use the env var for a machine-wide default and the CLI flag for per-client or per-project overrides.
|
||||
|
||||
The `vestige` CLI also honors `VESTIGE_DATA_DIR`, so use the same directory when inspecting or exporting a custom MCP instance:
|
||||
|
||||
```bash
|
||||
VESTIGE_DATA_DIR=./.vestige vestige stats
|
||||
VESTIGE_DATA_DIR=./.vestige vestige portable-export ./vestige-portable.json
|
||||
```
|
||||
|
||||
**Multiple Named Instances:**
|
||||
|
||||
For power users who want both global AND project memory:
|
||||
|
|
@ -132,7 +177,7 @@ Claude Code config - for "Storm":
|
|||
|
||||
## Data Safety
|
||||
|
||||
**Important:** Vestige stores data locally with no cloud sync, redundancy, or automatic backup.
|
||||
**Important:** Vestige stores data locally. v2.1.1 adds user-controlled file-backed sync through `vestige sync`, but Vestige does not run a hosted cloud service, background replication daemon, or automatic backup for you.
|
||||
|
||||
| Use Case | Risk Level | Recommendation |
|
||||
|----------|------------|----------------|
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue