MNM-001 · SIDE A SHARED MEMORY SERVER 33⅓ · SELF-HOSTED

One memory for every AI agent.

Claude Code, Cursor, opencode, Codex CLI — each forgets when the session ends. Mnema is a small self-hosted server that gives them all one common brain: structured memory, hybrid RAG, project maps and auto-recall. One SQLite file, one protocol (MCP), your own hardware.

01

Agents forget. Mnema doesn't.

problem / solution
WITHOUT A HUB
  • A decision made in Claude Code is invisible to Cursor an hour later
  • Switching desktop → laptop means re-explaining everything
  • Every agent re-derives project context from scratch
  • "I learned X yesterday" lives in scrollback — or nowhere
WITH MNEMA
  • Decisions saved once, with rationale, retrievable by any agent
  • Project maps follow you across every machine on your mesh
  • Relevant memory is auto-injected into each message — precisely filtered
  • Notes and research live in a searchable RAG store, forever

No vector-DB cluster. No message queue. No Docker layer. Just enough infrastructure to make memory persistent and searchable across tools and devices.

02

System modules

9 subsystems · one core

Memory

Decisions, preferences, how-tos — saved with rationale. Hybrid search: FTS5 BM25 + sqlite-vec vector KNN, merged with Reciprocal Rank Fusion. Importance multiplier × time decay scoring.

memory_save / memory_search

RAG store

Ingest notes, READMEs, research write-ups. Markdown-aware chunking, Gemini embeddings, hybrid retrieval with source references. Falls back to keyword-only search without an API key.

rag_add / rag_search

Auto-recall

Hooks inject relevant memory into every message and project context (bridge) at session start — gated by a semantic-evidence precision filter. Few results, high signal.

recall / recall_feedback

Project maps

One structured record per project: architecture, module map, decisions, current focus, next steps. Agents stop re-discovering your codebase — project_get("name") and go.

project_get / project_update

MCP + REST

24 MCP tools over Streamable HTTP for agents; a mirror REST API for scripts and the web UI. One implementation, two doors. Works with Claude Code, Cursor, opencode, Codex CLI, ChatGPT…

/mcp · /api/*

Local AI orchestration

Route bulk text work to LM Studio / Ollama at zero API cost, and image / video generation to ComfyUI — all from one API, callable by any connected agent.

local_llm / media_generate

Relationship graph

Memories, projects, documents and tags form a network. Explore it as an infinitely expanding interactive graph — follow any node outward.

web ui / graph

Cross-device sync

Local-first, last-write-wins: millisecond timestamps with a deterministic content-hash tie-break. Every replica converges to the same winner — write anywhere, read everywhere.

LWW · private mesh

Web UI

A 1-bit / bitmap-aesthetic dashboard for browsing memory, RAG documents, projects and prompts — from any browser, including your phone (installable PWA).

react · dashboard
03

Signal path

devices ↔ hub ↔ storage

■ embeddings are computed on the hub only — clients send raw text, the API key lives in exactly one place · drag sideways to pan the diagram

04

Tool tracklist

MNM-001 · 24 tracks

Every capability is an MCP tool. Point any MCP client at /mcp and the full set is callable — same tools, every agent, every device.

  1. 01.memory_searchhybrid recall — BM25 + vector KNN, fused with RRF
  2. 02.memory_savestore decisions, preferences & how-tos with rationale
  3. 03.memory_updateamend a memory the moment it's falsified
  4. 04.memory_deletecontradictory memory is worse than none
  5. 05.recallprecision-gated context injection, per message
  6. 06.recall_feedbackgrade what surfaced — the filter learns
  7. 07.rag_addmarkdown-aware chunking + embeddings
  8. 08.rag_searchhybrid document retrieval with source refs
  9. 09.project_listevery project map on the hub
  10. 10.project_getsummary, stack, decisions, focus — instantly
  11. 11.project_updatekeep the map current; stale maps mislead agents
  12. 12.project_add_decisionrecord the choice — and the why
  13. 13.project_deleteretire a map cleanly
  14. 14.prompt_listrole prompt library index
  15. 15.prompt_getarchitect · reviewer · debugger · security · devops · ml
  16. 16.session_logwhat was done, what's half-finished, what's next
  17. 17.session_recent"where was I?" — across devices
  18. 18.skill_listshared skill set index
  19. 19.skill_savepublish a skill to every device at once
  20. 20.machine_statuswho's online on the mesh
  21. 21.machine_registerenroll a new device
  22. 22.local_llmroute bulk work to LM Studio / Ollama — zero API cost
  23. 23.workflow_listComfyUI workflow registry
  24. 24.media_generateimage & video via ComfyUI, one API

total running time: 24 tools · all in daily use · REST mirrors every track

05

Quick start

node 22+ · any OS
OPTION A ·· one-click installer·····
# macOS / Linux
$ curl -fsSL https://raw.githubusercontent.com/fthsrbst/mnema/master/scripts/install.sh | bash

# Windows (PowerShell)
> irm https://raw.githubusercontent.com/fthsrbst/mnema/master/scripts/install.ps1 | iex
OPTION B ·· manual·····
$ git clone https://github.com/fthsrbst/mnema.git
$ cd mnema
$ npm ci
$ npm run build
$ cp .env.example .env   # set HUB_TOKEN
$ npm run dev
→ http://127.0.0.1:8033
RASPBERRY PI ·· always-on deploy·····
$ curl -fsSL https://raw.githubusercontent.com/\
  fthsrbst/mnema/master/deploy/setup-pi.sh | bash

# installs Node 22, builds server + web UI,
# generates .env with a random HUB_TOKEN,
# installs a systemd unit + nightly backup cron
CONNECT AN AGENT ·· claude code·····
$ claude mcp add --transport http --scope user hub <HUB-URL>/mcp \
    --header "Authorization: Bearer <TOKEN>"

# Cursor / Windsurf / opencode / Codex CLI: same endpoint, see README

No GEMINI_API_KEY? The server still runs — it falls back to keyword-only (FTS) search instead of hybrid. Nothing crashes; you lose semantic recall until you add a key. Embeddings are only ever computed server-side.