Memoria
Sends opt-in webhook notifications and alerts, such as digests, scans, approvals, and pending drafts, to Discord.
Supports optional end-to-end encrypted .memsync bundle sync across devices via a shared Dropbox folder.
Reads Git state and history for resume and timeline context, and shares team memories via a .memoria/brain.md file in the repository.
Supports optional end-to-end encrypted .memsync bundle sync across devices via a shared iCloud folder.
Exports memories to an Obsidian vault and imports an entire notes folder back into Memoria.
Uses Ollama models as an optional local inference backend for LLM-grade memory extraction and embeddings.
Supports optional OpenAI-compatible inference endpoints for LLM-grade memory extraction and embeddings.
Supports optional end-to-end encrypted .memsync bundle sync across devices via a shared Syncthing folder.
Sends opt-in webhook notifications and alerts, such as digests, scans, approvals, and pending drafts, to Telegram.
Memoria
A second brain for every AI coding tool — 100% local.
Claude Code, Codex, Gemini CLI, Copilot, Antigravity, opencode, VS Code, Cursor, Windsurf — one shared memory that remembers everything you've ever done and feeds it into your next session.
No cloud. No account. Nothing leaves your computer.
English · Bahasa Indonesia
npx @xinzzu/memoria@latest server # then open http://127.0.0.1:48210Capture in Claude Code, continue in Codex: the context comes with you. If Memoria saves you a re-explain, a star helps others find it.
Why?
Every AI tool has short-term amnesia. Claude doesn't remember yesterday's session. Codex doesn't know you decided "12-column grid" in Gemini CLI. And when you hit your usage limit mid-task and switch to another tool, you explain everything all over again.
Memoria closes that gap. It watches your AI tool sessions, extracts what matters — facts, decisions, tasks, fixed errors — and hands it to the next session, in any tool, automatically.
Built for the limit-hopping workflow: hit your limit at 14:30, open a different tool at 14:31 — and it already knows what you were working on.
Related MCP server: Leteo
How it works
flowchart TB
subgraph S["1. AI tool sessions (9 sources)"]
S1["Claude Code · Codex · Gemini CLI · Copilot · Antigravity<br/>opencode · VS Code · Cursor · Windsurf"]
end
subgraph C["2. Capture & triggers"]
W["Watcher<br/>real-time ingest (jsonl / sqlite / logs)"]
P["Pre-limit trigger<br/>usage-limit snapshot → immediate resume path"]
end
subgraph E["3. Extraction (tiered, never blocked)"]
direction LR
T0["Tier 0<br/>Heuristics<br/>(no model)"]
T1["Tier 1<br/>Ollama<br/>(local LLM)"]
T2["Tier 2<br/>OpenAI-compatible<br/>(opt-in)"]
end
subgraph K["4. Local core — ~/.memoria (SQLite)"]
DB[("Memories · tasks · graph<br/>FTS5 + embeddings + links")]
RES["Resume engine<br/>hot path on idle (~4 min) / pre-limit"]
end
subgraph O["5. Consumers & outputs"]
MCP["MCP server<br/>stdio + HTTP /mcp<br/>12 clients · 7 tools"]
CTX["Context injection<br/>AGENTS.md · CLAUDE.md · GEMINI.md"]
UI["Dashboard<br/>Electron tray · 9 views"]
NT["Webhooks / notifications<br/>Discord · Telegram · generic"]
end
subgraph X["Optional: encrypted sync (same user, multi-device)"]
SYNC[".memsync bundles (E2E AES-256-GCM)<br/>manual export/import or shared folder"]
end
S1 --> W
S1 -. "limit event" .-> P
W --> E
P --> RES
E --> DB
DB <--> RES
RES --> CTX
DB <--> MCP
DB --> UI
DB --> NT
DB <-. "encrypted ops (no embeddings/secrets/transcripts)" .-> SYNCCapture — work in any AI tool; Memoria watches sessions in real time (jsonl/sqlite/logs) and, on a reported usage limit, takes a deterministic work snapshot.
Extract — the active tier (heuristics, Ollama, or OpenAI-compatible) turns transcripts into memories (facts, decisions, tasks, fixes), indexed by FTS5 + embeddings + graph links.
Store locally — everything lives in a local SQLite brain (
~/.memoria); embeddings/dialects are never mixed across models.Resume — when a session goes idle (~4 min) or pre-limit fires, the resume engine extracts the newest session first and injects an idempotent SESSION RESUME block into
AGENTS.md/CLAUDE.md/GEMINI.md.Consume — any of the 12 MCP clients can
recall/remember/curate context via stdio or the HTTP bridge (/mcp), while the dashboard and opt-in webhooks surface the same state.Sync (optional) — replicate the library across your devices with end-to-end encrypted
.memsyncbundles (manual or shared folder); embeddings, secrets, settings, transcripts, and local paths never sync.
Highlights
🔄 Capture from 9 tools | Claude Code, Codex, opencode, Gemini CLI, Copilot, Antigravity, VS Code (Copilot Chat), Cursor, Windsurf |
⏸️ Resume engine | A SESSION RESUME block auto-injected into AGENTS.md / CLAUDE.md / GEMINI.md: open tasks, locked decisions, current branch, dirty files |
⚡ Pre-limit trigger | The moment your AI tool reports a usage limit, Memoria captures a work snapshot (files, commands, git state) and injects the resume block immediately — before you're kicked out |
🧩 MCP bridge — one URL, every tool | MCP over HTTP at |
🤖 Self-editing memory | Agents don't just read the brain — they curate it: |
✅ Tasks view | Every task your AI sessions promised, in one checkable board |
🧠 Tiered intelligence | Works with no model at all (heuristics + automatic triage, no manual approval), with Ollama, or any OpenAI-compatible endpoint (LM Studio, llama.cpp, vLLM, cloud — opt-in) |
🔍 Hybrid retrieval | Keyword (FTS5 trigram) + embeddings + graph centrality, fuzzy-tolerant — measured on a reproducible benchmark: hit@5 92.8–100% with zero LLM calls |
🕸️ Memory graph | True 3D force graph (2D fallbacks), degree-priority labels with anti-overlap, hover focus on neighbors, zoom & pan |
📋 Tasks & timeline | Per-project activity + git history + weekly digest |
🔎 Global palette | Search & copy memories from anywhere; quick-note hotkey |
👥 Team project brain | Opt-in |
🔐 Encrypted sync (optional) | E2E encrypted |
🔔 Webhooks & notifications | Opt-in alerts to Discord, Telegram, or generic JSON webhooks (digest, scan, approvals, pending drafts) |
🌐 EN / ID interface | English-first, Bahasa Indonesia one click away |
🧹 Self-cleaning | Daily consolidation merges near-duplicates; tool-noise filter keeps the review inbox honest; one-click noise cleanup |
💾 Backups & export | Auto-backup (last 10, WAL-safe), restore, export to Markdown / JSON / Obsidian vault — and import a whole notes folder back in |
Requirements
Minimum | Notes | |
Windows | 10/11 |
|
Linux | .deb distros / AppImage | tray needs libappindicator |
macOS | 12+ | Apple Silicon & Intel |
Node.js | ≥ 22.5 | only when building from source |
Ollama | optional | upgrade path for LLM-grade extraction & embeddings |
RAM | 4 GB (8 GB recommended) | works CPU-only |
Quickstart
1 · Install
Download from the latest release:
OS | Package |
Windows |
|
Linux |
|
macOS (Apple Silicon) |
|
macOS (Intel) |
|
macOS builds are not notarized yet: drag to Applications, then right-click → Open the first time.
Memoria lives in the tray and starts capturing automatically.
Headless / CLI (servers, WSL, devcontainers) — no Electron, Node.js 22.5 or newer:
npx @xinzzu/memoria@latest server # dashboard + API + MCP on http://127.0.0.1:48210
npm install -g @xinzzu/memoria # or install once, then: memoria server
memoria help # all commands2 · First run — no model required
On first launch a setup assistant lists the AI tools found on your machine, connects the ones you pick, imports their past sessions, and shows what Memoria now remembers about your recent projects — usually within a minute.
Out of the box, Memoria runs on Tier 0 heuristics: sessions are captured and turned into memories. Noise (tool output, shell listings, bare paths) and duplicates are archived automatically, strong signals become active, and the few uncertain drafts are re-checked daily — you never have to approve thousands of items by hand. Every triage batch can be undone. Search, tasks, timeline, graph, handoff — everything works. Secrets (API keys, tokens, private keys, passwords) are redacted before anything is stored.
Want LLM-grade extraction and embeddings later?
ollama pull qwen2.5-coder:3b
ollama pull nomic-embed-textMemoria detects them automatically (within ~5 minutes) and moves up a tier — nothing to reconfigure, no data migrations. Prefer LM Studio / llama.cpp / a cloud endpoint instead? Settings → Engine.
3 · Register your tools
Open the Integrations tab → one-click registration per tool, or via CLI:
node dist/engine/index.js integrate claude12 supported targets (config paths per the official MCP clients docs):
Claude Code (~/.claude.json), Claude Desktop (claude_desktop_config.json),
Codex CLI (~/.codex/config.toml), opencode, Gemini CLI (~/.gemini/settings.json),
Copilot CLI (~/.copilot/mcp-config.json), Antigravity, Cursor (~/.cursor/mcp.json
via the HTTP bridge), Windsurf (~/.codeium/windsurf/mcp_config.json),
VS Code (~/.vscode/mcp.json, "type": "http"), Cline (globalStorage
settings), Zed (settings.json). All registrations merge into your existing
configs — nothing is overwritten.
Prefer zero config? Any MCP-capable tool can also point straight at the HTTP bridge:
url: http://127.0.0.1:48210/mcpThen start a new session and tell your agent:
Recall the decisions from previous sessions in this project.Nine MCP tools ship out of the box: recall (project-scoped, token budget),
remember (ADD/UPDATE/NOOP smart decisions), update_memory, forget,
related, project_context (compact index by default), get_memory (full text
for selected ids), file_context (fixed errors, decisions and open tasks that
mention a file), and build_context (one ready-to-paste context block with a
character budget). When a newer decision replaces an older one about the same
subject, the old one is marked superseded and drops out of the resume block.
Claude Code hooks are installed together with the MCP server: a new Claude Code session
starts with the project's resume context, and each turn, compaction, and session end is
imported immediately (memoria hooks install | remove | status).
Beyond coding tools: import your ChatGPT or Claude history (the data-export .zip) and
keep memories in an Obsidian vault in both directions — edit or delete a note there and
Memoria follows.
4 · CLI
node dist/engine/index.js scan # scan all tools now
node dist/engine/index.js recall "docker issue"
node dist/engine/index.js status
node dist/engine/index.js mcp # MCP stdio mode
# MCP over HTTP (bridge for any AI tool):
# url: http://127.0.0.1:48210/mcp
# encrypted sync (same user, multiple machines)
node dist/engine/index.js sync setup # create group + recovery code
node dist/engine/index.js sync status
node dist/engine/index.js sync export --out ./bundle.memsync
node dist/engine/index.js sync import --in ./bundle.memsync --embed
node dist/engine/index.js sync folder set /path/to/shared # auto-sync via shared folder
node dist/engine/index.js sync folder status
node dist/engine/index.js sync conflictsThe resume engine — limit-hopping
The core feature. You hit a usage limit mid-task and switch tools; the new tool should already know what you were doing.
When transcript activity goes quiet (~4 minutes = session ended), Memoria runs the hot path: scan → extract the newest session first → inject. Within ~5 minutes, every context convention file in the project contains an idempotent, marked block:
And when your AI tool itself reports a usage limit, the pre-limit trigger fires the same pipeline immediately — a deterministic work snapshot (files touched, commands run, errors, last message, git branch/dirty files) is saved as a memory, the newest session is extracted with priority, and the resume block is injected before you're kicked out. You can even get a webhook ping on your phone: "resume brain is ready — switch tools whenever you're ready."
## SESSION RESUME
> claude · 14:32 · branch: feat/auth
**Open tasks:**
- [ ] finish the refresh-token endpoint in routes/api.ts
**Locked decisions (do not repeat):**
- JWT access tokens, 15 min — not sessions
**Dirty files (git):** src/auth/middleware.ts, src/auth/routes.ts
_Continue the work above — do not re-litigate locked decisions._Injected into AGENTS.md (Codex/opencode), CLAUDE.md (Claude Code) and GEMINI.md (Gemini CLI) — each target toggleable in Settings — plus a one-click resume prompt for tools that don't read context files.
Tiered intelligence
Tier | Engine | Needs | Extraction | Embeddings |
2 | OpenAI-compatible | explicit opt-in + endpoint | ✓ LLM-grade | ✓ model-grade |
1 | Ollama | installed locally | ✓ LLM-grade | ✓ model-grade |
0 | Heuristics (default) | nothing | rule-based + auto-triage | local hash (256-dim) |
Automode: Ollama when it's running and the model exists, otherwise heuristics. Never touches the cloud.Engine changes apply instantly — no restart.
Embedding dialects are never mixed: search, dedupe and the graph never compare vectors across models.
Encrypted sync (optional)
Sync the same memory library across your machines (same user) with end-to-end encrypted bundles:
Transport: manual
.memsyncexport/import or a shared folder watched by Memoria (Dropbox, iCloud Drive, Syncthing, network share).Crypto: 256-bit group key + recovery code, AES-256-GCM bundles (HKDF per file, AAD-bound header), idempotent apply with HLC/LWW and conflict/tombstone handling.
Never synced: embeddings, secrets/API keys, settings, raw transcripts, or machine-local paths.
Setup:
memoria sync setup(create/join group) then export/import ormemoria sync folder set.Dashboard: Settings → Sync shows group/device status, pending outbox, last export/import, shared-folder state/error, and recent conflicts (group setup, passphrase unlock, and manual bundle transfer remain CLI).
Sync hardening (key rotation/revocation, rollback protection, performance pass) is planned (M5).
Dashboard
Nine views, English or Bahasa Indonesia:
Overview — greeting, pastel stat cards, 14-day activity chart (messages and memory creations — heuristic work included), "Recently worked on", resume-ready projects, setup checklist
Memories — full library: search with term highlighting, kind/project/topic/age filters, approval inbox with one-click noise cleanup, archive
Projects — per-project activity, pending-draft visibility, click through to timelines
Timeline — session trail + git history
Handoff — generate, copy, or inject the resume block
Tasks — the AI-session promise board
Graph — memory connections in 3D, Obsidian-style interactions, anti-overlap labels
Integrations — 12 MCP targets, one-click registration
Settings — two-pane layout: data sources, engine tiers, behavior, data/backup, notifications, and sync
Global: Ctrl/⌘ + Shift + M quick note · Ctrl/⌘ + Shift + Space memory palette
(both rebindable in Settings).
Privacy
Capture, extraction, search — 100% local in
~/.memoriaby default.The OpenAI-compatible tier is the only way data leaves the machine, and it requires explicit opt-in with a visible privacy warning.
API keys and webhook secrets are always encrypted and never returned to the UI: Electron uses safeStorage; the CLI / npm mode uses AES-256-GCM with a master key kept in the macOS Keychain, Linux Secret Service (
secret-tool), or Windows DPAPI, falling back to an owner-only key file.Secrets are redacted from transcripts before storage;
<private>…</private>blocks and excluded projects are never stored.The local API (
127.0.0.1:48210) requires a token. The desktop app passes it automatically; for headless modememoria serverprints a one-time sign-in link, andmemoria tokenprints it again. Data folder and database files are owner-only (0700/0600).Encrypted sync bundles are end-to-end encrypted and never include embeddings, secrets, settings, transcripts, or machine-local paths.
Stale, low-importance memories are archived automatically (forgetting curve); backups keep the last 10 versions.
Development
git clone https://github.com/xinzzu/Memoria && cd Memoria
npm install
npm run dev # TypeScript watch mode
npm run build # compile once
npm test # build + node --test (66 tests)
npm run start # Electron dev (engine on port 48210)
npm run check:ui # audit UI selectors + structure
npm run dist # Windows installer
npm run dist:linux # AppImage + .deb
npm run dist:mac # .dmg + .zip (macOS only)Tests run against
dist/(notsrc/). For an isolated server, useMEMORIA_DATA_DIR=$(mktemp -d)and never touch the live~/.memoriaDB or port48210.
Project structure
src/
├── engine/
│ ├── config.ts # per-OS data sources & tool config
│ ├── http.ts # local API (127.0.0.1:48210) + static dashboard
│ ├── ingest/ # watcher + per-tool parsers (claude, codex, vscdb, …)
│ ├── extract/ # provider tiers, heuristics, ollama, openai-compat,
│ │ # entities, topics, task lifecycle, dedupe
│ ├── retrieve/search.ts # hybrid retrieval (FTS5 trigram + embeddings + centrality)
│ ├── retrieve/contextblock.ts # build_context — one ready-to-paste context block
│ ├── sync/ # E2E encrypted sync (keys, bundles, export/apply,
│ │ # shared-folder transport, CLI, embed backfill)
│ ├── mcp/server.ts # MCP server (stdio + HTTP bridge, 7 tools)
│ ├── store/ # SQLite (node:sqlite), migrations v1-v7, backup, secure storage
│ ├── extract/snapshot.ts # F4 zero-AI work snapshots + pre-limit trigger
│ ├── extract/consolidate.ts # daily near-duplicate merging (zero-LLM)
│ ├── import/markdown.ts # Obsidian vault / notes folder import
│ ├── notify/webhook.ts # opt-in Discord/Telegram/generic notifications
│ ├── handoff.ts # resume engine + multi-file injection
│ └── index.ts # CLI entry
├── electron/main.ts # tray, dashboard, global hotkeys
web/ # dashboard UI (vanilla JS, EN/ID i18n)
scripts/ # icon generator, UI selector audit, search bench,
# retrieval eval (hit@1/@5, MRR)
docs/ # design docs (e.g. sync-design.md)
tests/ # node --test suites (run against dist/)
ROADMAP.md # execution plan & current position
CHANGELOG.md # release notesTech
TypeScript · Node 24 (node:sqlite, FTS5) · Electron 37 · chokidar · MCP SDK · vanilla JS dashboard
FAQ
Does my data leave my computer?
No. Capture, extraction and search all run locally in ~/.memoria. The cloud tier exists but
only activates if you explicitly configure it.
Can I sync between machines?
Yes. Create/join a sync group (memoria sync setup), then export/import .memsync bundles
manually or point Memoria at a shared folder (Dropbox/iCloud/Syncthing/network share) via CLI
or Settings → Sync. Bundles are end-to-end encrypted and never include embeddings, secrets,
settings, transcripts, or machine-local paths.
Do I need Ollama? No. Heuristics work with zero models and triage their own output automatically. Ollama is an upgrade path, detected automatically when you install it.
Which tools are supported?
Claude Code, Codex, opencode, Gemini CLI, Copilot, Antigravity — plus VS Code, Cursor and
Windsurf capture, and a generic /api/import endpoint for anything else.
Will memories grow forever? No, three ways: stale low-importance memories are archived automatically (forgetting curve), a daily consolidation pass merges near-duplicates, and tool-noise (status lines, badges, markdown debris) is filtered out of extraction — with a one-click cleanup for the stored backlog.
What happens when I hit my AI tool's usage limit? Memoria detects the limit message in the transcript and immediately captures a work snapshot, extracts the session with priority, and injects the resume block into your context files — before you're kicked out. Switch tools and the next session already knows what you were doing. Optionally, a webhook pings your phone.
Can I connect an AI tool without editing config files?
Yes — any MCP-capable client can point at the HTTP bridge: http://127.0.0.1:48210/mcp.
Or use one-click registration for 12 clients in the Integrations tab.
Can Memoria notify me outside the dashboard? Yes, opt-in. Configure Discord, Telegram, or a generic JSON webhook in Settings → Notifications for digest/scan/approval/draft events. Webhook secrets are stored encrypted when available.
UI language? English by default; Bahasa Indonesia one click away in Settings.
Documentation
ROADMAP.md — execution plan, phases and current position
CHANGELOG.md — release notes
docs/sync-design.md — encrypted sync design and status
License
MIT © 2026 Memoria
Made in Indonesia — so your AI agents never forget again.
Available Tools
9 toolsbuild_contextA
One ready-to-use context block for a project: auto-maintained project brief + key memories + optional query matches + 1-hop relations, capped to maxChars. Ideal first call at session start.
Inputs: project (required), query, maxChars.
file_contextA
Before editing a file, ask what is known about it: fixed errors, decisions, open tasks and preferences that mention this file path. Pass an absolute or relative path.
Inputs: path (required), limit, project.
forgetA
Delete a stale or wrong memory. Pass the memory id for a direct delete, or a query: a confident match is deleted immediately, otherwise candidates are listed for you to pick an explicit id.
Inputs: id, query.
get_memoryA
Fetch the full text of specific memories by id (ids come from project_context, recall, or related).
Inputs: ids (required).
project_contextA
Fetch the latest context of a project: decisions, pending tasks, completed work. Default mode "index" returns one compact line per memory with its id (cheap on tokens); call get_memory with the ids you need for full text. Use mode "full" to get everything at once.
Inputs: project (required), mode, limit.
recallA
Search memories of previous work by keywords/question. Returns facts, decisions, tasks and fixed errors. Call at session start!
Inputs: query (required), mode, limit, project, +1 more.
rememberA
Store an important memory (decision, fact, user preference, completed/pending task) so every tool remembers it.
Inputs: kind (required), content (required), project, importance.
update_memoryA
Correct an existing memory: replace its content (auto re-embedded so semantic search stays accurate), change its kind, or adjust importance. Pass the memory id from recall.
Inputs: id (required), kind, content, importance.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The core CRUD operations (get_memory, remember, update_memory, forget) are cleanly distinct, and recall vs related vs file_context are differentiated by input type and intent. The main soft spot is the read-side overlap: project_context in 'full' mode and build_context both return a ready-made context block, and recall with a query partly duplicates build_context's optional query matches, though the descriptions do enough to steer selection.
There is no single convention: snake_case verb_noun (get_memory, update_memory, build_context), bare verbs (recall, remember, forget), and noun-only names (project_context, file_context, related) coexist. Each name is individually readable and snake_case formatting is uniform, but the verb-vs-noun alternation breaks predictability.
Nine tools is well within the sweet spot for a memory/knowledge server, and each one corresponds to a distinct step in the memory lifecycle (store, search, retrieve, relate, update, delete, assemble context). No tool appears redundant padding.
Full lifecycle is covered: create (remember), read (get_memory, recall, project_context, file_context, build_context), update (update_memory), delete (forget), and graph traversal (related). Minor gaps remain — no way to enumerate or browse all stored memories, filter by kind/project, or bulk-delete/prune stale entries.
Maintenance
Related MCP Connectors
Shared AI memory. ChatGPT, Claude, Cursor and any MCP app read and write the same memory.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseBqualityBmaintenancePersistent, local memory for AI coding agents that learns how you work, not just what you said. Supports Claude Code, Codex CLI, Cursor, and any MCP client.7998 PyPI77MIT
- AlicenseAqualityBmaintenancePersistent memory for AI coding agents, storing decisions, bug fixes, conventions, and discoveries in a local SQLite database and automatically recalling them when relevant. Works with Claude Code, Codex, Cursor, Gemini CLI, and other MCP-compatible agents.224MIT
- FlicenseNot gradedqualityCmaintenanceLocal-first memory for AI coding agents. Indexes your Claude Code, Codex, Cursor, Cline and Gemini CLI history by repo/branch/worktree and hands a context capsule (decisions, touched files, next steps) to the next agent over MCP.-
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code, Codex and other MCP agents to share one bounded, persistent memory across sessions, so a session starts from what earlier sessions learned instead of re-reading the repository. Storage and retrieval run locally on SQLite full-text search with per-client tokens and scopes, and optional local model enrichment, without any paid model in the path.1MIT