Persistent knowledge base & long-term memory for Claude Code.

Synaipse stores project knowledge (ADRs, API docs, bug analyses, code patterns, research notes) as Markdown in a configurable vault. An MCP server exposes the vault to Claude Code with full-text, wikilink, tag and (optional) semantic search. A vanilla-TS web UI lets you browse, edit and visualise the same data.

• Obsidian-compatible Markdown vault — open it in Obsidian alongside Claude
• MCP first — .mcp.json ships in the repo; Claude Code picks it up automatically
• Pluggable embeddings — none, huggingface (in-process ONNX, zero-Docker), ollama (local), or voyage (hosted)
• Live web UI — search, graph, backlinks; SSE-pushed updates when Claude writes

Quickstart

cp .env.example .env             # EMBEDDINGS_PROVIDER defaults to "none"
npm install
npm run build
npm run vault:init
npm run web                      # http://localhost:5757

That's the zero-dependency path (fulltext only, no Docker, no sign-up). For semantic search pick a provider:

# local, free, needs Docker
npm run docker:up:ollama && npm run web

# hosted, best quality, needs VOYAGE_API_KEY in .env
npm run docker:up:voyage && npm run web

Server mode (MariaDB-backed)

For multi-user / multi-instance deployments, run notes + chats out of MariaDB instead of the filesystem vault:

npm run docker:up:server                # mariadb:11.7 on port 3307
SYNAIPSE_MODE=server npm run web        # web + MCP boot against the DB

See the architecture ADR for the rationale, the server-storage smoke scripts for the verification shape, and the SYNAIPSE_MARIADB_* block in .env.example for the required environment variables. ngit history is silent (NoopHistory) in server mode until the async commit-worker lands.

Detailed walkthrough: doc/getting-started.md.

Documentation

Index: doc/README.md.

Monorepo

Use from Claude Code

The repo ships a project-level .mcp.json. After npm run build, launch Claude Code from the repository root — the synaipse MCP server starts automatically over stdio and reads .env. See doc/claude-code-setup.md.

Available tools: synaipse_get_project, _verify_history, _snapshot_list, _search, _read_note, _write_note, _update_note, _delete_note, _list_notes, _list_tags, _notes_by_tag, _backlinks, _outgoing_links, _link_note, _related, _suggest_links, _graph, _recent, _prime, _stale, _todos, _log_session, _remember. Full reference: doc/mcp-tools.md.

For shared multi-project vaults, set SYNAIPSE_PROJECT=<name> per Claude Code session — writes are then auto-scoped to Memory/<name>/ and tagged project/<name>. See doc/configuration.md.

Stack

• TypeScript (ESM, strict, exactOptionalPropertyTypes)
• VTS — runtime type schemas
• Qdrant — vector DB (optional, Docker)
• Embeddings: Voyage AI (hosted) or Ollama (local) or disabled
• marked — Markdown rendering
• Cytoscape.js — graph visualization (lazy-loaded chunk)
• MCP — Claude Code integration
• Vite — bundler

Vault

Vault location is configurable via SYNAIPSE_VAULT_PATH. Format is Obsidian-compatible Markdown:

• YAML frontmatter (---)
• Wikilinks [[Note Name]] (alias [[Note Name|label]], section [[Note Name#Heading]])
• Tags #tag inline or as frontmatter list

Recommended structure inside the vault:

Memory/
├── decisions/
├── architecture/
├── code-patterns/
├── libraries/
├── bugs/
├── infrastructure/
├── research/
└── sessions/

Details: doc/vault-format.md.

Scripts

npm run build              tsc --build across all packages
npm test                   vitest run
npm run lint               eslint
npm run vault:init         seed vault from templates/ (substitutes Memory/Project/ with SYNAIPSE_PROJECT)
npm run mcp                start MCP server (stdio)
npm run web                start API + Vite dev server
npm run docker:up:voyage   start qdrant only
npm run docker:up:ollama   start qdrant + ollama + model pull
npm run docker:up:server   start mariadb (server-mode hot-tier)
npm run docker:down        stop all
npm run crawl:github-stars crawl your starred repos into Crawler/github/starred/
npm run crawl:devto        crawl the latest 100 dev.to articles into Crawler/devto/articles/