apunkt/vestige
1
0
Fork 0
mirror of https://github.com/samvallad33/vestige.git synced 2026-05-10 16:22:36 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions
vestige/packages/vestige-mcp-npm
History
Sam Valladares 8178beb961 feat(v2.0.5): Intentional Amnesia — active forgetting via top-down inhibitory control 
First AI memory system to model forgetting as a neuroscience-grounded
PROCESS rather than passive decay. Adds the `suppress` MCP tool (#24),
Rac1 cascade worker, migration V10, and dashboard forgetting indicators.

Based on:
- Anderson, Hanslmayr & Quaegebeur (2025), Nat Rev Neurosci — right
  lateral PFC as the domain-general inhibitory controller; SIF
  compounds with each stopping attempt.
- Cervantes-Sandoval et al. (2020), Front Cell Neurosci PMC7477079 —
  Rac1 GTPase as the active synaptic destabilization mechanism.

What's new:
* `suppress` MCP tool — each call compounds `suppression_count` and
  subtracts a `0.15 × count` penalty (saturating at 80%) from
  retrieval scores during hybrid search. Distinct from delete
  (removes) and demote (one-shot).
* Rac1 cascade worker — background sweep piggybacks the 6h
  consolidation loop, walks `memory_connections` edges from
  recently-suppressed seeds, applies attenuated FSRS decay to
  co-activated neighbors. You don't just forget Jake — you fade
  the café, the roommate, the birthday.
* 24h labile window — reversible via `suppress({id, reverse: true})`
  within 24 hours. Matches Nader reconsolidation semantics.
* Migration V10 — additive-only (`suppression_count`, `suppressed_at`
  + partial indices). All v2.0.x DBs upgrade seamlessly on first launch.
* Dashboard: `ForgettingIndicator.svelte` pulses when suppressions
  are active. 3D graph nodes dim to 20% opacity when suppressed.
  New WebSocket events: `MemorySuppressed`, `MemoryUnsuppressed`,
  `Rac1CascadeSwept`. Heartbeat carries `suppressed_count`.
* Search pipeline: SIF penalty inserted into the accessibility stage
  so it stacks on top of passive FSRS decay.
* Tool count bumped 23 → 24. Cognitive modules 29 → 30.

Memories persist — they are INHIBITED, not erased. `memory.get(id)`
returns full content through any number of suppressions. The 24h
labile window is a grace period for regret.

Also fixes issue #31 (dashboard graph view buggy) as a companion UI
bug discovered during the v2.0.5 audit cycle:

* Root cause: node glow `SpriteMaterial` had no `map`, so
  `THREE.Sprite` rendered as a solid-coloured 1×1 plane. Additive
  blending + `UnrealBloomPass(0.8, 0.4, 0.85)` amplified the square
  edges into hard-edged glowing cubes.
* Fix: shared 128×128 radial-gradient `CanvasTexture` singleton used
  as the sprite map. Retuned bloom to `(0.55, 0.6, 0.2)`. Halved fog
  density (0.008 → 0.0035). Edges bumped from dark navy `0x4a4a7a`
  to brand violet `0x8b5cf6` with higher opacity. Added explicit
  `scene.background` and a 2000-point starfield for depth.
* 21 regression tests added in `ui-fixes.test.ts` locking every
  invariant in (shared texture singleton, depthWrite:false, scale
  ×6, bloom magic numbers via source regex, starfield presence).

Tests: 1,284 Rust (+47) + 171 Vitest (+21) = 1,455 total, 0 failed
Clippy: clean across all targets, zero warnings
Release binary: 22.6MB, `cargo build --release -p vestige-mcp` green
Versions: workspace aligned at 2.0.5 across all 6 crates/packages

Closes #31
2026-04-14 17:30:30 -05:00
..
bin fix: v2.0.1 release — fix broken installs, CI, security, and docs 2026-03-01 20:20:14 -06:00
scripts fix: v2.0.1 release — fix broken installs, CI, security, and docs 2026-03-01 20:20:14 -06:00
.gitignore feat(v2.0.5): Intentional Amnesia — active forgetting via top-down inhibitory control 2026-04-14 17:30:30 -05:00
.npmignore fix(npm): add .npmignore to exclude cache and binaries 2026-01-26 23:50:40 -06:00
package.json feat(v2.0.5): Intentional Amnesia — active forgetting via top-down inhibitory control 2026-04-14 17:30:30 -05:00
README.md fix: v2.0.1 release — fix broken installs, CI, security, and docs 2026-03-01 20:20:14 -06:00

README.md

vestige-mcp-server

Vestige MCP Server - A synthetic hippocampus for AI assistants.

Built on 130 years of cognitive science research, Vestige provides biologically-inspired memory that decays, strengthens, and consolidates like the human mind.

Installation

npm install -g vestige-mcp-server

This automatically downloads the correct binary for your platform (macOS, Linux, Windows) from GitHub releases.

What gets installed

Command Description
vestige-mcp MCP server for Claude integration
vestige CLI for stats, health checks, and maintenance

Verify installation

vestige health

Usage with Claude Code

claude mcp add vestige vestige-mcp -s user

Then restart Claude.

Usage with Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vestige": {
      "command": "vestige-mcp"
    }
  }
}

CLI Commands

vestige stats          # Memory statistics
vestige stats --states # Cognitive state distribution
vestige health         # System health check
vestige consolidate    # Run memory maintenance cycle

Features

  • FSRS-6 Algorithm: State-of-the-art spaced repetition for optimal memory retention
  • Dual-Strength Memory: Bjork & Bjork (1992) - Storage + Retrieval strength model
  • Synaptic Tagging: Memories become important retroactively (Frey & Morris 1997)
  • Semantic Search: Local embeddings via nomic-embed-text-v1.5 (768 dimensions)
  • Local-First: All data stays on your machine - no cloud, no API costs

Storage & Memory

Vestige uses SQLite for storage. Your memories are stored on disk, not in RAM.

  • Database limit: 216TB (SQLite theoretical max)
  • RAM usage: ~64MB cache (configurable)
  • Typical usage: 1 million memories ≈ 1-2GB on disk

You'll never run out of space. A heavy user creating 100 memories/day would use ~1.5GB after 10 years.

Embeddings

On first use, Vestige downloads the nomic-embed-text-v1.5 model (~130MB). This is a one-time download and all subsequent operations are fully offline.

The model is stored in .fastembed_cache/ in your working directory, or you can set a global location:

export FASTEMBED_CACHE_PATH="$HOME/.fastembed_cache"

Environment Variables

Variable Description Default
VESTIGE_DATA_DIR Data storage directory ~/.vestige
VESTIGE_LOG_LEVEL Log verbosity info
FASTEMBED_CACHE_PATH Embeddings model location ./.fastembed_cache

Troubleshooting

"Could not attach to MCP server vestige"

  1. Verify binary exists: which vestige-mcp
  2. Test directly: vestige-mcp (should wait for stdio input)
  3. Check Claude logs: ~/Library/Logs/Claude/ (macOS)

"vestige: command not found"

Reinstall the package:

npm install -g vestige-mcp-server

Embeddings not downloading

The model downloads on first ingest or search operation. If Claude can't connect to the MCP server, no memory operations happen and no model downloads.

Fix the MCP connection first, then the model will download automatically.

Supported Platforms

Platform Architecture
macOS ARM64 (Apple Silicon), x86_64 (Intel)
Linux x86_64
Windows x86_64

License

AGPL-3.0-only