vestige/CONTRIBUTING.md

Contributing to Vestige

Thank you for your interest in contributing to Vestige! This guide covers everything you need to get started.

Project Overview

Vestige is a cognitive memory MCP server written in Rust. It gives AI agents persistent long-term memory using neuroscience-backed algorithms (FSRS-6, prediction error gating, synaptic tagging, spreading activation, memory dreaming).

Architecture:

vestige/
├── crates/
│   ├── vestige-core/       # Cognitive engine, FSRS-6, search, embeddings, storage
│   └── vestige-mcp/        # MCP server, Axum dashboard, WebSocket, tool handlers
├── apps/
│   └── dashboard/          # SvelteKit + Three.js 3D dashboard
├── packages/
│   ├── vestige-init/       # npx @vestige/init installer
│   └── vestige-mcp-npm/    # npm binary wrapper
└── tests/
    └── vestige-e2e-tests/  # End-to-end MCP protocol tests

Development Setup

Prerequisites

• Rust (1.91+ stable): rustup.rs
• Node.js (v22+): nodejs.org
• pnpm (v9+): npm install -g pnpm

Getting Started

git clone https://github.com/samvallad33/vestige.git
cd vestige

# Build the dashboard (required for include_dir! embedding)
cd apps/dashboard && pnpm install && pnpm build && cd ../..

# Build the Rust workspace
cargo build

# Run tests
VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace

Environment Variables

Variable	Purpose
VESTIGE_TEST_MOCK_EMBEDDINGS=1	Use mock embeddings in tests (skips ONNX model download)
VESTIGE_DB_PATH	Override default database path (~/.vestige/vestige.db)

Running Tests

# All tests (746+ total)
VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace

# Core library tests only (352 tests)
VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test -p vestige-core --lib

# MCP server tests only (378 tests)
VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test -p vestige-mcp --lib

# E2E MCP protocol tests (requires release build)
cargo build --release -p vestige-mcp
cargo test -p vestige-e2e-tests --test mcp_protocol -- --test-threads=1

# Dashboard build test
cd apps/dashboard && pnpm build

Building

# Debug build
cargo build -p vestige-mcp

# Release build (23MB binary with embedded dashboard)
cargo build --release -p vestige-mcp

# The release binary is at target/release/vestige-mcp

Release Profile

The release profile uses lto = true, codegen-units = 1, opt-level = "z", and strip = true for minimum binary size.

Code Style

Rust

# Format
cargo fmt --all

# Lint (zero warnings policy)
cargo clippy --workspace -- -D warnings

• Rust 2024 edition
• Standard rustfmt defaults
• All public items should have doc comments
• Tests go in #[cfg(test)] mod tests at the bottom of each file

TypeScript/Svelte (Dashboard)

cd apps/dashboard
pnpm check    # Svelte type checking
pnpm lint     # ESLint

Project Structure

vestige-core

The cognitive engine. Key modules:

Module	Purpose
fsrs/	FSRS-6 spaced repetition (21 parameters, power-law decay)
neuroscience/	Synaptic tagging, spreading activation, hippocampal index, importance signals
advanced/	Prediction error gating, dreaming, compression, cross-project learning
search/	Hybrid search (BM25 + semantic), HyDE, reranker, temporal search
embeddings/	fastembed (Nomic Embed v1.5), ONNX inference
storage/	SQLite + FTS5 + USearch HNSW

vestige-mcp

The MCP server and dashboard. Key modules:

Module	Purpose
server.rs	MCP JSON-RPC server (rmcp 0.14)
cognitive.rs	CognitiveEngine — 29 stateful modules
tools/	One file per MCP tool (24 tools)
dashboard/	Axum HTTP + WebSocket + event bus

apps/dashboard

SvelteKit 2 + Three.js + Tailwind CSS. Pages:

• /dashboard — 3D memory graph with force-directed layout
• /dashboard/memories — Searchable memory browser
• /dashboard/timeline — Chronological memory timeline
• /dashboard/feed — Real-time WebSocket event stream
• /dashboard/explore — Connection explorer (associations, chains, bridges)
• /dashboard/intentions — Intention manager
• /dashboard/stats — System health, retention distribution, module status

Pull Request Process

1. Fork the repository and create a feature branch from main
2. Write tests for new functionality
3. Ensure all checks pass: cargo fmt, cargo clippy, cargo test
4. Build the dashboard if you modified apps/dashboard/
5. Keep commits focused: One logical change per commit
6. Open a PR with a clear description

PR Checklist

• cargo fmt --all — code is formatted
• cargo clippy --workspace -- -D warnings — zero warnings
• VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace — all tests pass
• Dashboard builds (if modified): cd apps/dashboard && pnpm build
• No secrets, API keys, or credentials in code

Good First Issues

Look for issues labeled good first issue. These are scoped, well-defined tasks ideal for new contributors:

• Adding tests for existing modules
• Documentation improvements
• Dashboard UI enhancements
• New MCP tool implementations

Adding a New MCP Tool

1. Create crates/vestige-mcp/src/tools/your_tool.rs
2. Implement pub fn schema() -> Tool and pub fn execute(...) -> Result<CallToolResult>
3. Register in crates/vestige-mcp/src/tools/mod.rs
4. Add tests in the same file
5. Update tool count in README and CLAUDE.md

Adding a New Cognitive Module

1. Add the module to crates/vestige-core/src/neuroscience/ or advanced/
2. Add the field to CognitiveEngine in crates/vestige-mcp/src/cognitive.rs
3. Initialize it in CognitiveEngine::new() and new_with_events()
4. Write comprehensive tests (aim for 10+ per module)
5. Document the neuroscience citation in the module's doc comment

Issue Reporting

Use the issue templates:

• Bug Report: Include OS, install method, IDE, vestige version, and steps to reproduce
• Feature Request: Describe the problem, proposed solution, and alternatives considered

Code of Conduct

We are committed to providing a welcoming and inclusive environment. All contributors are expected to be respectful, constructive, and collaborative. Harassment and discrimination will not be tolerated.

License

By contributing, you agree that your contributions will be licensed under AGPL-3.0-only (LICENSE), the same license as the project.

---

Questions? Open a discussion or reach out to the maintainers.