SynaptoMind

Lightweight thought-graph engine. Capture, link, cluster, and retrieve thoughts via HTTP API or MCP server.

Architecture

SynaptoMind runs as two processes:

1. Main process — HTTP API (Hono) + MCP server (stdio/HTTP) + background jobs
2. Embedder subprocess — local embedding generation via @huggingface/transformers (IPC)

The embedder runs as a child process spawned by the main process. It communicates via Bun IPC and handles model loading, embedding generation, and idle timeout. The main process manages all HTTP/IO, database operations, and background tasks.

Quick Start

Prerequisites

• Bun runtime
• Internet connection (for initial setup)

1. Install dependencies

bun install

This also runs postinstall which downloads the vec0.so SQLite extension from sqlite-vec releases. The binary is platform-specific (linux/macOS, x86_64/aarch64) and is not committed to the repository.

2. Configure

cp config.json.example config.json

Edit config.json to customize settings. Key options:

• server.port — HTTP API port (default: 3005)
• server.host — bind address (default: 127.0.0.1)
• mcp.httpPort — MCP HTTP transport port (default: 3006)
• embedder.model — HuggingFace model for embeddings (default: Xenova/multilingual-e5-small)
• db.path — SQLite database path (default: ./data/synaptomind.db)

All settings can be overridden via environment variables (see src/config.ts for the full mapping).

3. Start

bun run src/index.ts

Authentication

Both the HTTP API and MCP HTTP transport require bearer token auth.

If neither is set, random UUID tokens are generated at startup — one for the API, one for MCP (they are separate). The generated tokens are printed to stderr on startup.

# Set a persistent token (recommended for production)
export SYNAPTOMIND_SECRET=my-secret-token

Endpoints

Features

• Graph storage — thoughts, edges, projects, tags, smart notes
• Hybrid search — vector (vec0) + BM25 (FTS5) + entity matching
• Local embeddings — @huggingface/transformers, no API keys
• MCP server — 30+ tools, stdio + HTTP transport
• Auto-clustering — batch grouping by embedding proximity
• Background jobs — decay, dreamer, self-improve, git sync

Docker

docker compose up -d

The Docker image builds from source. Volumes mount ./data and ./config.json.

Set SYNAPTOMIND_SECRET in your docker-compose environment for persistent auth:

environment:
  - SYNAPTOMIND_SECRET=your-secret-token

Without it, a random token is generated on each restart and printed to docker logs.

Config

All settings in config.json. Priority: env vars > config.json > defaults.

See config.json.example for all options. Auth tokens are configured via env vars only (SYNAPTOMIND_SECRET, SYNAPTOMIND_SERVICE_TOKEN).

Custom Instructions

The MCP server sends instructions to the AI agent on startup. By default, it uses built-in instructions. To customize them:

1. Create a markdown file (e.g., instructions.md)
2. Set the path in config.json:

"mcp": {
  "instructionsFile": "./instructions.md"
}

Or via environment variable:

export SYNAPTOMIND_MCP_INSTRUCTIONS_FILE=./instructions.md

If the file is not found, the server falls back to default instructions and logs a warning.

API Examples

All /api/* endpoints require Authorization: Bearer <token> header. See Authentication above.

Create a thought

curl -X POST http://127.0.0.1:3005/api/thoughts \
  -H "Authorization: Bearer $SYNAPTOMIND_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"content": "First session went well", "tags": ["retrospective"]}'

Search thoughts

curl "http://127.0.0.1:3005/api/thoughts/search?q=session+retrospective&limit=5" \
  -H "Authorization: Bearer $SYNAPTOMIND_SECRET"

Health check

curl http://127.0.0.1:3005/health

MCP Tools

The MCP server exposes 30+ tools organized by domain:

Testing

bun test

Linting

bunx biome check src/

License

MIT