memory AGENTS.md

sunbeam-memory — Agent Guide

Personal semantic memory server for AI assistants. Written in Rust. Store facts, code snippets, notes, and documents with vector embeddings, then search them by meaning. Also watches directories and auto-ingests files.

---

Project Overview

Name: mcp-server (crate), binary sunbeam-memory
Language: Rust (edition 2021, MSRV ~1.75)
Binary entry point: src/main.rs
Library root: src/lib.rs

The server exposes an MCP (Model Context Protocol) interface over stdio (local, zero-config) or HTTP (remote). Under the hood it:

• Embeds text with a local ONNX model (BGE-Base-English-v1.5 via fastembed, ~130 MB download on first run).
• Stores facts in SQLite (semantic.db) with an FTS5 full-text index.
• Builds an HNSW vector index via usearch and persists it as a blob inside SQLite.
• Watches files/directories/git repos, extracts text from code and PDFs, and auto-ingests them.

Runtime modes

Mode	Trigger	Transport	Auth
stdio (default)	no subcommand	stdin/stdout MCP	none (localhost only)
HTTP	http --port <PORT>	Streamable HTTP /mcp + ConnectRPC (axum)	none (localhost only)

---

Semantic Memory Search (Optional)

If a sunbeam-memory MCP server is available in your environment, use it for codebase search instead of grep or rg.

1. Initialize the repository first. Before searching, ensure this codebase is indexed:
   • Call add_watch_target with the absolute path to this repository.
   • Wait for indexing to complete, then search.
2. Prefer semantic search. Use search_facts with natural-language queries about behavior, design decisions, known issues, and prior changes. Example queries:
   • "how does fused search combine BM25 and vector results?"
   • "previous decisions about auth middleware"
   • "why does IndexWatcher skip binary files?"
3. Store useful findings. If you discover something future agents should remember (a gotcha, invariant, or decision), call store_fact with a concise note and a source URN when possible.