apunkt/vestige
1
0
Fork 0
mirror of https://github.com/samvallad33/vestige.git synced 2026-04-25 00:36:22 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: update CONTRIBUTING.md for v2.0

Browse source 
Rewrite for MCP server architecture (was Tauri app), correct license
to AGPL-3.0, add project structure guide, test commands, new tool/module
contribution guides, and dashboard build instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Sam Valladares 2026-02-22 03:17:52 -06:00
parent fc70964534
commit 22831af509
1 changed files with 154 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

231
CONTRIBUTING.md
View file

@ -1,137 +1,214 @@
# Contributing to Vestige
Thank you for your interest in contributing to Vestige! This document provides guidelines and information to help you get started.
Thank you for your interest in contributing to Vestige! This guide covers everything you need to get started.
## Project Overview
Vestige is a Tauri-based desktop application combining a Rust backend with a modern web frontend. We welcome contributions of all kinds—bug fixes, features, documentation, and more.
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** (stable, latest recommended): [rustup.rs](https://rustup.rs)
- **Node.js** (v18 or later): [nodejs.org](https://nodejs.org)
- **pnpm**: Install via `npm install -g pnpm`
- **Platform-specific dependencies**: See [Tauri prerequisites](https://tauri.app/v1/guides/getting-started/prerequisites)
- **Rust** (1.85+ stable): [rustup.rs](https://rustup.rs)
- **Node.js** (v22+): [nodejs.org](https://nodejs.org)
- **pnpm** (v9+): `npm install -g pnpm`
### Getting Started
1. Clone the repository:
```bash
git clone https://github.com/samvallad33/vestige.git
cd vestige
```
```bash
git clone https://github.com/samvallad33/vestige.git
cd vestige
2. Install frontend dependencies:
```bash
pnpm install
```
# Build the dashboard (required for include_dir! embedding)
cd apps/dashboard && pnpm install && pnpm build && cd ../..
3. Run in development mode:
```bash
pnpm tauri dev
```
# 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
```bash
# Run Rust tests
cargo test
# All tests (734 total)
VESTIGE_TEST_MOCK_EMBEDDINGS=1 cargo test --workspace
# Run with verbose output
cargo test -- --nocapture
# 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
```bash
# Build Rust backend (debug)
cargo build
# Debug build
cargo build -p vestige-mcp
# Build Rust backend (release)
cargo build --release
# Release build (22MB binary with embedded dashboard)
cargo build --release -p vestige-mcp
# Build frontend
pnpm build
# Build complete Tauri application
pnpm tauri build
# 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
We follow standard Rust conventions enforced by `rustfmt` and `clippy`.
```bash
# Format code
cargo fmt
# Format
cargo fmt --all
# Run linter
cargo clippy -- -D warnings
# Lint (zero warnings policy)
cargo clippy --workspace -- -D warnings
```
Please ensure your code passes both checks before submitting a PR.
- 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/JavaScript
### TypeScript/Svelte (Dashboard)
```bash
# Lint and format
pnpm lint
pnpm format
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 (21 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. **Keep commits focused**: One logical change per commit with clear messages.
5. **Update documentation** if your changes affect public APIs or behavior.
6. **Open a PR** with a clear description of what and why.
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
- [ ] Code compiles without warnings
- [ ] Tests pass locally
- [ ] Code is formatted (`cargo fmt`)
- [ ] Clippy passes (`cargo clippy -- -D warnings`)
- [ ] Documentation updated (if applicable)
- [ ] `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
When reporting bugs, please include:
Use the issue templates:
- **Summary**: Clear, concise description of the issue
- **Environment**: OS, Rust version (`rustc --version`), Node.js version
- **Steps to reproduce**: Minimal steps to trigger the bug
- **Expected vs actual behavior**
- **Logs/screenshots**: If applicable
For feature requests, describe the use case and proposed solution.
- **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 and considerate in all interactions
- Welcome newcomers and help them get started
- Accept constructive criticism gracefully
- Focus on what is best for the community
Harassment, discrimination, and hostile behavior will not be tolerated.
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 the same terms as the project:
- **MIT License** ([LICENSE-MIT](LICENSE-MIT))
- **Apache License 2.0** ([LICENSE-APACHE](LICENSE-APACHE))
You may choose either license at your option.
By contributing, you agree that your contributions will be licensed under **AGPL-3.0-only** ([LICENSE](LICENSE)), the same license as the project.
---
Questions? Open a discussion or reach out to the maintainers. We're happy to help!
Questions? Open a [discussion](https://github.com/samvallad33/vestige/discussions) or reach out to the maintainers.