Commit graph

30 commits

Author SHA1 Message Date
Sam Valladares
6be374d115 docs(readme): v2.0.6 "Composer" header + honesty on Intel Mac / Windows
Three changes, all aimed at new-user experience:

1. v2.0.6 "Composer" section up top — explicitly names the three user-
   happiness wins: six live graph reactions (was one), intentions page
   priority + trigger rendering fix, and the opt-in
   `VESTIGE_SYSTEM_PROMPT_MODE=full` composition mandate (default stays
   minimal so nothing gets imposed on users' system prompts).

2. v2.0.5 "Intentional Amnesia" block strengthened — clarifies the
   distinction between passive Ebbinghaus decay, Anderson 1994
   retrieval-induced forgetting, and v2.0.5's top-down active
   suppression (Anderson 2025 + Cervantes-Sandoval 2020). Adds a
   "Forgetting" row to the RAG-vs-Vestige comparison table.

3. Install section honesty on Intel Mac + Windows — the pre-built
   binary download links 404 on those targets because of upstream
   toolchain gaps (`ort-sys` lacks Intel Mac prebuilts in the
   2.0.0-rc.11 release pinned by fastembed 5.13.2; `usearch 2.24.0`
   hit a Windows MSVC compile break tracked as usearch#746). Replaced
   the dead links with a `cargo build --release -p vestige-mcp`
   snippet that works today.
2026-04-18 18:33:31 -05:00
Sam Valladares
e9b2aa6d4d
Clarify AI terminology in README
Some checks failed
CI / Test (macos-latest) (push) Has been cancelled
CI / Test (ubuntu-latest) (push) Has been cancelled
Test Suite / Unit Tests (push) Has been cancelled
Test Suite / MCP E2E Tests (push) Has been cancelled
Test Suite / Dashboard Build (push) Has been cancelled
Test Suite / Code Coverage (push) Has been cancelled
CI / Release Build (aarch64-apple-darwin) (push) Has been cancelled
CI / Release Build (x86_64-unknown-linux-gnu) (push) Has been cancelled
Test Suite / User Journey Tests (push) Has been cancelled
Updated terminology
2026-04-16 14:27:46 -05:00
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
Sam Valladares
04781a95e2 feat: v2.0.4 "Deep Reference" — cognitive reasoning engine + 10 bug fixes
New features:
- deep_reference tool (#22): 8-stage cognitive reasoning pipeline with FSRS-6
  trust scoring, intent classification (FactCheck/Timeline/RootCause/Comparison/
  Synthesis), spreading activation expansion, temporal supersession, trust-weighted
  contradiction analysis, relation assessment, dream insight integration, and
  algorithmic reasoning chain generation — all without calling an LLM
- cross_reference (#23): backward-compatible alias for deep_reference
- retrieval_mode parameter on search (precise/balanced/exhaustive)
- get_batch action on memory tool (up to 20 IDs per call)
- Token budget raised from 10K to 100K on search + session_context
- Dates (createdAt/updatedAt) on all search results and session_context lines

Bug fixes (GitHub Issue #25 — all 10 resolved):
- state_transitions empty: wired record_memory_access into strengthen_batch
- chain/bridges no storage fallback: added with edge deduplication
- knowledge_edges dead schema: documented as deprecated
- insights not persisted from dream: wired save_insight after generation
- find_duplicates threshold dropped: serde alias fix
- search min_retention ignored: serde aliases for snake_case params
- intention time triggers null: removed dead trigger_at embedding
- changelog missing dreams: added get_dream_history + event integration
- phantom Related IDs: clarified message text
- fsrs_cards empty: documented as harmless dead schema

Security hardening:
- HTTP transport CORS: permissive() → localhost-only
- Auth token panic guard: &token[..8] → safe min(8) slice
- UTF-8 boundary fix: floor_char_boundary on content truncation
- All unwrap() removed from HTTP transport (unwrap_or_else fallback)
- Dream memory_count capped at 500 (prevents O(N²) hang)
- Dormant state threshold aligned (0.3 → 0.4)

Stats: 23 tools, 758 tests, 0 failures, 0 warnings, 0 unwraps in production

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-09 16:15:26 -05:00
Aleksei Savin
d10a336ccc Add Codex integration docs 2026-04-05 18:50:57 +03:00
Sam Valladares
c6090dc2ba fix: v2.0.1 release — fix broken installs, CI, security, and docs
Critical fixes:
- npm postinstall.js: BINARY_VERSION '1.1.3' → '2.0.1' (every install was 404ing)
- npm package name: corrected error messages to 'vestige-mcp-server'
- README: npm install command pointed to wrong package
- MSRV: bumped from 1.85 to 1.91 (uses floor_char_boundary from 1.91)
- CI: removed stale 'develop' branch from test.yml triggers

Security hardening:
- CSP: restricted connect-src from wildcard 'ws: wss:' to localhost-only
- Added X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy headers
- Added frame-ancestors 'none', base-uri 'self', form-action 'self' to CSP
- Capped retention_distribution endpoint from 10k to 1k nodes
- Added debug logging for WebSocket connections without Origin header

Maintenance:
- All clippy warnings fixed (58 total: redundant closures, collapsible ifs, no-op casts)
- All versions harmonized to 2.0.1 across Cargo.toml and package.json
- CLAUDE.md updated to match v2.0.1 (21 tools, 29 modules, 1238 tests)
- docs/CLAUDE-SETUP.md updated deprecated function names
- License corrected to AGPL-3.0-only in root package.json

1,238 tests passing, 0 clippy warnings.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 20:20:14 -06:00
Sam Valladares
c2d28f3433 feat: Vestige v2.0.0 "Cognitive Leap" — 3D dashboard, HyDE search, WebSocket events
The biggest release in Vestige history. Complete visual and cognitive overhaul.

Dashboard:
- SvelteKit 2 + Three.js 3D neural visualization at localhost:3927/dashboard
- 7 interactive pages: Graph, Memories, Timeline, Feed, Explore, Intentions, Stats
- WebSocket event bus with 16 event types, real-time 3D animations
- Bloom post-processing, GPU instanced rendering, force-directed layout
- Dream visualization mode, FSRS retention curves, command palette (Cmd+K)
- Keyboard shortcuts, responsive mobile layout, PWA installable
- Single binary deployment via include_dir! (22MB)

Engine:
- HyDE query expansion (intent classification + 3-5 semantic variants + centroid)
- fastembed 5.11 with optional Nomic v2 MoE + Qwen3 reranker + Metal GPU
- Emotional memory module (#29)
- Criterion benchmark suite

Backend:
- Axum WebSocket at /ws with heartbeat + event broadcast
- 7 new REST endpoints for cognitive operations
- Event emission from MCP tools via shared broadcast channel
- CORS for SvelteKit dev mode

Distribution:
- GitHub issue templates (bug report, feature request)
- CHANGELOG with comprehensive v2.0 release notes
- README updated with dashboard docs, architecture diagram, comparison table

734 tests passing, zero warnings, 22MB release binary.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 03:07:25 -06:00
Sam Valladares
697c981e49 docs: update README for v1.9.1 — 21 tools, autonomic features, memory_graph
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-21 02:04:58 -06:00
Sam Valladares
5b90a73055 feat: Vestige v1.9.1 AUTONOMIC — self-regulating memory with graph visualization
Retention Target System: auto-GC low-retention memories during consolidation
(VESTIGE_RETENTION_TARGET env var, default 0.8). Auto-Promote: memories
accessed 3+ times in 24h get frequency-dependent potentiation. Waking SWR
Tagging: promoted memories get preferential 70/30 dream replay. Improved
Consolidation Scheduler: triggers on 6h staleness or 2h active use.

New tools: memory_health (retention dashboard with distribution buckets,
trend tracking, recommendations) and memory_graph (subgraph export with
Fruchterman-Reingold force-directed layout, up to 200 nodes).

Dream connections now persist to database via save_connection(), enabling
memory_graph traversal. Schema Migration V8 adds waking_tag, utility_score,
times_retrieved/useful columns and retention_snapshots table. 21 MCP tools.

v1.9.1 fixes: ConnectionRecord export, UTF-8 safe truncation, link_type
normalization, utility_score clamping, only-new-connections persistence,
70/30 split capacity fill, nonexistent center_id error handling.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-21 02:02:06 -06:00
Sam Valladares
ce520bb246 chore: license AGPL-3.0, zero clippy warnings, CHANGELOG through v1.6.0
License:
- Replace MIT/Apache-2.0 with AGPL-3.0-only across all crates and npm packages
- Replace LICENSE file with official GNU AGPL-3.0 text
- Remove LICENSE-MIT and LICENSE-APACHE

Code quality:
- Fix all 44 clippy warnings (zero remaining)
- Collapsible if statements, redundant closures, manual Option::map
- Remove duplicate #[allow(dead_code)] attributes in deprecated tool modules
- Add Default impl for CognitiveEngine
- Replace manual sort_by with sort_by_key

Documentation:
- Update CHANGELOG with v1.2.0, v1.3.0, v1.5.0, v1.6.0 entries
- Update README with v1.6.0 highlights and accurate stats (52K lines, 1100+ tests)
- Add fastembed-rs/ to .gitignore
- Add fastembed-rs to workspace exclude

1115 tests passing, zero warnings, RUSTFLAGS="-Dwarnings" clean.
2026-02-19 03:00:39 -06:00
Sam Valladares
5b7d22d427 docs: update README for v1.5.0 — 23 tools, cognitive engine, dreaming 2026-02-18 23:39:40 -06:00
Sam Valladares
3fce1f0b70 feat: v2.0 distribution — IDE integrations, zero-config installer, README overhaul
- Add integration guides for Xcode 26.3, Cursor, VS Code, JetBrains, Windsurf
- First cognitive memory server with documented Xcode 26.3 MCP support
- Add npx @vestige/init — zero-config CLI that auto-detects IDEs and injects config
- Overhaul README: "The open-source cognitive engine for AI"
- Add "Why Not Just Use RAG?" comparison and cognitive science stack docs
- Update license badge to AGPL-3.0
2026-02-12 17:18:15 -06:00
Sam Valladares
eb16d684fc fix: use platform cache dir for fastembed models
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>
2026-01-27 02:32:23 -06:00
Sam Valladares
497f149b64 docs: restructure README for 30-second onboarding
README: 1,565 → 196 lines (87% reduction)

New structure:
- Quick Start above the fold (download → connect → test)
- Why Vestige in 5-row table
- Tools reference
- CLAUDE.md trigger words
- Collapsible troubleshooting
- Links to detailed docs

New docs/:
- FAQ.md: 870 lines of community Q&A
- SCIENCE.md: FSRS-6, dual-strength memory, neuroscience
- STORAGE.md: Global, per-project, multi-Claude setup
- CLAUDE-SETUP.md: Full templates for proactive memory
- CONFIGURATION.md: CLI commands, env vars

All content preserved, just reorganized for scannability.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 02:28:39 -06:00
Sam Valladares
a8eb9e7bae docs: update README for v1.1.1 release
- Add v1.1.1 changelog with bug fixes
- Add pre-built binary download options for all platforms
- Replace basic CLAUDE.md with comprehensive proactive memory setup
- Add release badge
- Update version table and references

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 02:12:48 -06:00
Sam Valladares
e5b27ff1e5 docs: fix README installation and cache documentation
- Add -s user flag to claude mcp add commands for user scope install
- Correct fastembed cache location docs (.fastembed_cache in CWD, not ~/.cache/huggingface)
- Add troubleshooting section for .fastembed_cache folder in project directories
- Include FASTEMBED_CACHE_PATH env var workaround

Fixes issues reported by Reddit user feedback.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 22:34:10 -06:00
Sam Valladares
1b9004f88e chore(v1.1): move stats tools to CLI, add feedback protocol
- Remove get_stats, health_check, run_consolidation from MCP server
- These tools now CLI-only: vestige stats, vestige health, vestige consolidate
- Add feedback protocol to server instructions (promote/demote guidance)
- Update README with CLI Admin Commands section and Feedback Tools table
- Update release note: "8 Cognitive Primitives + 3 CLI Admin Commands"

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 02:05:06 -06:00
Sam Valladares
a6ba67884d docs: professionalize data storage warning section
Replace casual tone with clear risk assessment table and
professional recommendations.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 01:48:16 -06:00
Sam Valladares
3023e58ce3 docs: add What's New in v1.1 section at top of README
Highlights v1.1 features prominently:
- Tool consolidation (29 → 8)
- New CLI binary commands
- Documentation improvements
- Backward compatibility note

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 01:41:34 -06:00
Sam Valladares
3ac85eeff4 docs: add version pinning and release tags documentation
- Document how to pin to specific versions
- List available versions (v1.0.0, v1.1.0)
- Add version check command

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 01:37:55 -06:00
Sam Valladares
36244f3c95 docs(faq): clarify Vestige vs Claude native memory compatibility
Address common question: users don't need to disable Claude's native
memory to use Vestige. They're independent systems that can run
simultaneously.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 01:34:56 -06:00
Sam Valladares
8bb6500985 feat(v1.1): consolidate 29 tools → 8 unified tools + CLI
Tool Consolidation:
- search: merges recall, semantic_search, hybrid_search
- memory: merges get_knowledge, delete_knowledge, get_memory_state
- codebase: merges remember_pattern, remember_decision, get_codebase_context
- intention: merges all 5 intention tools into action-based API

New CLI Binary:
- vestige stats [--tagging] [--states]
- vestige health
- vestige consolidate
- vestige restore <file>

Documentation:
- Verify all neuroscience claims against codebase
- Fix Memory States table: "Retention" → "Accessibility" with formula
- Clarify Spreading Activation: embedding similarity vs full network module
- Update Synaptic Tagging: clarify 9h/2h implementation vs biology
- Add comprehensive FAQ with 30+ questions
- Add storage modes: global, per-project, multi-Claude household
- Add CLAUDE.md setup instructions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-26 01:31:58 -06:00
Sam Valladares
29130c3068 fix: accurate science claims, security docs, remove hardcoded path
## Changes

### README.md
- Fix FSRS-6 formula: power law (not exponential Ebbinghaus)
- Correct formula: R(t,S) = (1 + factor × t/S)^(-w₂₀)
- Honest "The Science" table showing what's fully implemented vs inspired
- Added / indicators for implementation accuracy
- Transparency note about honest marketing

### demo.sh
- Remove hardcoded /Users/entity002 path (security/privacy)
- Use relative path with fallback: ${VESTIGE:-$(dirname "$0")/...}

### SECURITY.md (new)
- Document trust model and security boundaries
- Explain data storage locations
- List input validation measures
- Security contact process

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 20:29:37 -06:00
Sam Valladares
3a4a19fa20 docs: add comprehensive data backup warnings
- Detail what causes data loss (delete, corrupt, lost device)
- Clarify "For AI memory = fine, For critical data = not fine"
- Add automated cron job backup example
- Mention Time Machine / Windows Backup as options

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 20:00:51 -06:00
Sam Valladares
bd41ec3388 docs: comprehensive README rewrite
- Add one-liner CLI install (claude mcp add vestige vestige-mcp)
- Document first-run network requirement (~130MB model download)
- Add data storage locations and backup instructions
- Reorganize all 29 tools into clear tables
- Add troubleshooting section
- Honest framing of neuroscience claims

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 19:49:36 -06:00
Sam Valladares
f4842a12c1 Remove comparison section from README 2026-01-25 13:34:36 -06:00
Sam Valladares
dbb1c7bb3b Remove comparison column from Why Vestige section 2026-01-25 13:33:33 -06:00
Sam Valladares
a4d14f268c Update README with improved installation guide and 29 tools
- Simple 4-step Quick Start (2 minutes)
- Global install instructions (sudo cp to /usr/local/bin)
- Claude Code and Claude Desktop config examples
- Full 29-tool reference with descriptions
- Prediction Error Gating section with visual diagram
- Troubleshooting section
- Updating instructions

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 13:31:37 -06:00
Sam Valladares
bbd1c15b4a Add Prediction Error Gating and smart_ingest tool (26 tools total)
Implements neuroscience-inspired memory gating based on prediction error:
- New smart_ingest MCP tool that auto-decides CREATE/UPDATE/SUPERSEDE
- PredictionErrorGate evaluates semantic similarity vs existing memories
- Automatically supersedes demoted memories with similar new content
- Reinforces near-identical memories instead of creating duplicates
- Adds promote_memory/demote_memory/request_feedback tools

Thresholds:
- >0.92 similarity = Reinforce existing
- >0.75 similarity = Update/Merge
- <0.75 similarity = Create new
- Demoted + similar = Auto-supersede

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 13:30:03 -06:00
Sam Valladares
f9c60eb5a7 Initial commit: Vestige v1.0.0 - Cognitive memory MCP server
FSRS-6 spaced repetition, spreading activation, synaptic tagging,
hippocampal indexing, and 130 years of memory research.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 01:31:03 -06:00