membral
Use this server as a local MCP memory layer for coding agents and chats: search extracted memories, read their source sessions/conversations, browse recent/project activity, and resolve blockers.
Search extracted decisions, learnings, outcomes, blockers, and preferences by topic with
memory_search, including filters and source links.Recall records by repo or file path with
memory_recall(e.g. what shipped or what is tied to a path).Open a coding session with
get_code_session, including turns, files touched, summary, sub-agents, pagination, or a window around a cited turn.Open a chat with
get_conversation, with message pagination and optional full tool-call I/O.Get a coding session's short journey with
session_summary(threads, records, files).Search raw synced chats and coding sessions with
search_conversationsby keyword/semantic similarity and time filters.List coding projects (
list_code_projects) and recent chats/coding sessions (list_recent_conversations) with metadata.Mark a blocker as fixed with
memory_resolveby quoting the session text that states the fix.
Captures GitHub Copilot CLI and VS Code Copilot Chat transcripts, syncs them into the local store, and exposes memory search to Copilot through MCP.
Runs local embeddings with nomic-embed-text and can serve as the extraction model provider, such as qwen2.5:7b, for processing session turns.
Supports an OpenAI API key as an extraction-model provider for deriving decisions, learnings, and outcomes from session turns.
Membral
A local memory store for coding agents. Every decision and learning it extracts keeps its verbatim quote and links back to the session turn it came from, and your agents search it over MCP.
Membral runs in Docker on your machine. It saves your coding-agent sessions (Claude Code, Codex, opencode, Copilot,
Antigravity) in one store, extracts the decisions, learnings and outcomes, and keeps each one tied to its source: the
exact words said, and the turn to open (get_code_session with a turn) to read what was around them. An agent can
check a recalled fact against the transcript instead of trusting a summary.
How it fits together
flowchart LR
you([You])
subgraph inputs["Where your work happens"]
direction TB
subgraph agents["Coding agents"]
direction TB
cc[Claude Code]
cx[Codex CLI]
oc[opencode]
cp["GitHub Copilot<br/>CLI and VS Code"]
ag[Antigravity]
end
subgraph chats["Chat apps"]
direction TB
gpt[ChatGPT]
cai[Claude.ai]
end
end
cli["membral CLI<br/>hooks · 20-min sweep · import"]
ext["Chrome extension"]
subgraph stack["Your machine · membral local up (Docker)"]
direction TB
api["Membral app<br/>API · dashboard"]
mcp["MCP server<br/>memory_search · get_code_session · …"]
extract["Extraction<br/>runs on a timer"]
db[("Postgres + pgvector<br/>sessions · turns · memories")]
end
llm["Extraction model<br/>Claude login · Ollama 7B+ · API key"]
emb["Ollama on your machine<br/>nomic-embed-text"]
you -->|prompts| agents
you -->|chats| chats
agents -->|transcripts on disk| cli
chats -->|export file| cli
chats -->|open chat pages| ext
cli -->|upload sessions| api
ext -->|sync chats| api
api -->|store| db
db -->|new sessions| extract
extract <-->|turns in, records out| llm
extract -->|decisions · learnings · outcomes| db
api <-->|text in, vectors out| emb
agents <-->|MCP tool calls| mcp
mcp <-->|search| db
api -->|preamble · prompt lookup| cli
cli -->|added to the agent's context| agents
api -->|dashboard| you
style stack stroke-dasharray: 6 4In. The membral CLI reads each agent's transcripts from disk (end-of-session hooks and a 20-minute sweep) and
uploads them. Chats come in through the Chrome extension or an export file.
Stored and processed. The app keeps sessions, turns and memories in Postgres with pgvector. A timed job sends new turns to an extraction model and stores the decisions, learnings and outcomes that come back. A local embedding model turns text into vectors so search can compare meaning.
Back to your agent. Agents search over MCP. The CLI adds a preamble at session start and, in Claude Code, matching records at each prompt. The dashboard shows everything stored.
Related MCP server: ChatCrystal
What it does
One store for sessions from every agent, in one shape: turns, models, token usage, tools, files and sub-agents.
Extracts decisions, learnings and outcomes, each with its quote and a link to the session.
Searches by meaning, with keyword search as the fallback.
MCP tools (
memory_search,memory_recall,get_code_session) for any MCP-capable agent. Clients that only speak stdio can runmembral mcp.A session-start preamble and, in Claude Code only, prompt-time lookup.
ChatGPT and Claude.ai chats saved next to your coding sessions, and a dashboard to browse it all.
It is not live state: whether a PR is merged or what is deployed is checked in your forge. One store per person; no team or admin controls yet.
Run it locally
You need Node 22.5 or newer, Docker with Compose 2.23+ (40 GiB of VM disk), and one extraction model (step 1).
up starts three containers: Postgres with pgvector, PostgREST, and the Membral app, which serves sign-in itself and
runs extraction on a timer. Embeddings use a bundled model that downloads on first use (about 137 MB); Ollama is
optional.
Pick an extraction model by putting one choice in
~/.membral/local/.env(mkdir -p ~/.membral/localfirst):Claude subscription:
CLAUDE_CODE_OAUTH_TOKEN=<from claude setup-token>. Whenclaudeis on your PATH and no other choice is set,upselects theclaude-codeprovider for you.API key:
OPENAI_API_KEY=...(orOPENROUTER_API_KEY)Ollama: a 7B+ model such as
qwen2.5:7b, run withOLLAMA_CONTEXT_LENGTH=16384 ollama serve
Install and start it in one command:
npx membral local up. It starts the stack, prints the URL and an API key, and connects the agents it finds. Add--embeddings ollamato use Ollama'snomic-embed-textinstead of the bundled model.Check it:
npx membral local status(it prints anEmbeddings: ...line).
From a clone (contributors): git clone https://github.com/surajtripathy07/membral && cd membral && npm ci && npm run cli:install
builds the CLI and installs it globally, so membral replaces npx membral in the commands here.
up prints a sign-in URL and password and an API key; treat that output as a secret. The app is at
http://localhost:3000. The image is multi-arch (amd64 and arm64); if a pull fails, build it locally and pass --image. Image source builds, extraction setup, disk, logs, Linux notes and what works without an
extraction model are in docs/SELF-HOSTING.md.
Handoff notes are on by default locally: up writes MEMBRAL_HANDOFF_SYNTHESIS=1 (a session note is written after extraction) and MEMBRAL_HANDOFF_SEARCH=1 (memory_search can find notes) into .env; set either to 0 in your shell before membral local up, or in ~/.membral/local/.env, to turn it off.
Large stores (tens of GB of sessions) need Docker or Colima memory of 12 GB or more, for example colima start --memory 14.
up sizes Postgres memory to the Docker VM and warms the excerpts table in the background after it starts.
To run a second stack beside it (for example to test a branch), add --project <name> to local up|down|status|logs
(or set MEMBRAL_LOCAL_PROJECT) and pass a free --port value. Its files live in
~/.membral/local-<name> and its Docker volumes end in -<name>; the default stack is untouched. Both stacks write
the one local CLI profile, so the last up wins.
Why embeddings
Search compares meaning, so a question worded differently from the saved text still finds it. Without an embedder,
memory_search works on keywords only and says so ("SEARCH DEGRADED ... keyword-only results"), and the relevance
floor that drops weak matches is off. nomic-embed-text is the model whose thresholds are calibrated in this repo
(apps/cloud/src/lib/memory/similarity.ts). It runs on Ollama on your machine, so record text never leaves it.
Vectors are 1,536 wide, and smaller models are zero-padded. Chat and session-text search (search_conversations) is calibrated only for text-embedding-3-small, so with
nomic-embed-text it stays keyword-only and says so. The claude-code provider does no embeddings.
Chrome extension
It syncs ChatGPT and Claude.ai chats to your local stack.
npm run build --workspace=@membral/extension(targetshttp://localhost:3000; for another port build withVITE_CLOUD_URL=http://localhost:<port>, or save a Server URL in the options page, where Chrome asks permission).In
chrome://extensions, turn on Developer mode, choose Load unpacked, pickpackages/extension/dist.In the options page, paste the API key
npx membral local upprinted (it startslls_) and Save. The popup shows the server and "Connected with an API key".
Supported agents
Agent | Capture | Sync | MCP | Preamble |
Claude Code | yes | yes | yes | yes |
opencode | yes | yes | yes | yes |
GitHub Copilot (CLI + VS Code Copilot Chat) | yes | yes | yes | yes |
Codex CLI | yes | yes | yes | yes |
Antigravity | yes | yes | yes | yes |
Capture reads the agent's transcripts. Sync is membral sessions plus the sweep. MCP is search by the agent. The
preamble is added at session start. The per-prompt lookup is Claude Code only. A Claude Code plugin is an
alternative to the CLI hooks (docs/SELF-HOSTING.md).
Where your data goes
The local stack keeps everything on your machine. The exceptions are model calls: with an API key, session text
goes to that provider, and with a Claude login, to Anthropic through Claude Code. Saved: prompts, replies, tools
called, files touched and text written to files (capped). Tool output is not kept. Secrets are redacted by
pattern, and files such as .env keep no text. You choose which projects sync (~/.membral/sync.json).
To skip throwaway scratch directories, add path patterns to that file (* matches any characters):
{"excludePathPatterns":["/private/var/folders/*/membral-lab-*"]}. A project listed with enabled: true still syncs.
Commands
npx membral local up | status | logs <service> | downruns the stack (down --wipedeletes the data);npx membral local reembedmoves stored vectors to a new embedding model.membral setup,login(defaulthttp://localhost:3000),use,sessions,import <export.json>andstatus.membral --helplists every command.npm run smokechecks the dashboard renders the fixtures.
More
docs/SELF-HOSTING.md covers the stack in depth. CONTRIBUTING.md goes from clone to green gate to PR. docs/COMPARISON.md compares Membral with other ways of giving an agent memory.
License
MIT, see LICENSE. Source: github.com/surajtripathy07/membral.
Available Tools
9 toolsget_code_sessionA
Retrieve a specific coding session by ID (a memory_search record's session_id, a list_recent_conversations code row's id): its user-spine turns (what the human asked/decided/corrected), files touched, and per-session summary. To read the turns around a record, pass its session_id as id and its turn_idx as turn: you get only turns turn-window..turn+window (window default 8, max 40; max_chars default 12000 here) with focus {turn, window, first_idx, last_idx, total_turns}; prev_start/next_start, passed as start (without turn), read the turns before/after; start reads forward from there with the default 60000 chars. Whole-session paging below is the fallback. Long sessions come in parts: each call returns the session metadata and summary plus whole turns from start up to about max_chars of turn text (default 60000), with total_turns, total_chars, returned {start, end (exclusive)} and next_start. files_touched is on the first part only (up to 200 paths; files_touched_total and files_touched_omitted give the rest's count). When next_start is not null, call get_code_session again with the same id and start=next_start until next_start is null to read every turn. The first part also lists sub_agents: the sub-agent sessions this session spawned (id, agent_type, description, started_at, ended_at, turn_count, brief = first 160 chars of the task it was given; at most 200, sub_agents_total gives the full count); open one with get_code_session id=. When this session is itself a sub-agent, parent_session_id is the id of the session that spawned it. Use it to read what was actually said; use session_summary for a short threaded overview of the same session. Results are dated records of what sessions did, not the current state of a PR or issue; check that live.
Inputs: id (required), turn, start, window, +1 more.
get_conversationA
Retrieve a specific conversation by ID with its messages. Long conversations come in parts: each call returns whole messages from start up to about max_chars of content (default 60000), plus total_messages, total_chars, returned {start, end (exclusive)} and next_start. When next_start is not null, call get_conversation again with the same id and start=next_start until next_start is null to read the whole conversation. Tool calls/results are replaced by short stubs by default (see include_tool_io) so tool-heavy chats don't overflow the part budget.
Inputs: id (required), start, max_chars, include_tool_io.
list_code_projectsA
List the user's coding-agent projects (repos worked on via Claude Code etc.) with a rollup summary, session count, and last-active time
Inputs: no named parameters.
list_recent_conversationsA
List the user's recent sessions — chats AND coding sessions (Claude Code, opencode, Copilot CLI, Codex; main sessions, not sub-agents) — from the last few days by default, newest first, metadata only. Chat rows (type "chat"): id, title, source, created_at, updated_at, message_count. Code rows (type "code"): id, project_name, git_branch, source, started_at, ended_at, turn_count, summary (up to 200 chars). Defaults to the last 7 days and both kinds. Use it to find something by when it happened (e.g. yesterday's chat → since = yesterday's date, kind = chat), then open a chat with get_conversation id= or a coding session with get_code_session id=; both return long results in parts. Results are dated records of what sessions did, not the current state of a PR or issue; check that live.
Inputs: days, kind, limit, since, +1 more.
memory_recallA
Recall memory records BY REPO OR PATH (not by topic -- use memory_search for that). 'outcome' alone answers 'what shipped here lately'. Ordered kind-priority then recency. Read the turns around a record with get_code_session id=<session_id> turn=<turn_idx>. Records carry links to their sources when known: sha (the commit the session was on), paths (files it names, up to 5), ref_url (the ref's forge page). Open them directly; they locate sources, they do not report current state. Replaced records are hidden and paraphrases of one fact are served once with seen_in; every record carries as_of.
Inputs: kind, path, repo, limit, +3 more.
memory_resolveA
Mark a blocker as fixed. Call this right after you fix a blocker that Membral showed you (in the preamble, memory_search or memory_recall); quote your own or the user's message text that states the fix (not tool output, which is not stored). The blocker and its repeats are closed for every later session; the owner can restore it. The quote is checked against this session's transcript when it uploads and kept as the receipt. Only your own open blockers can be resolved.
Inputs: id (required), quote (required), recall_token.
memory_searchA
Search past sessions' learnings, decisions, blockers and other memory records by TOPIC (Postgres full-text search fused with semantic similarity) -- the tool for 'what did we decide/learn about X'. Filter by kind, scope, project, path, or since/days. A date phrase in the query ("last week", "yesterday", "Sept 20") is read as a time hint: it is taken out of the search text and records from that window rank higher, but older matches still come back (date_hint shows the reading); since/days are hard filters. Newer records win near-ties. since/days filter on the session's start time; each record's when is its session's end time (else start). Covers extracted, quote-verified records (extraction runs on sessions within about 30 days of upload; older extracted records stay searchable); a fact that was said but never extracted is only in the raw turns (search_conversations). When nothing is relevant enough, reason says why -- that is the answer, not an error. Records a newer record replaced are hidden unless include_superseded is true or the query names a past date; paraphrases of one fact are served as one record with seen_in (the number of sessions that said it); every record carries as_of, the day its session recorded it (true when recorded, not current state). Local installs return served: lines (records as JSON, raw session excerpts marked "raw excerpt") packed whole to max_tokens (default 3000). Else (hosted; raw_reason says why) ranked records cut at max_tokens (dropped_for_budget). A record's session_id is a code session: read the turns around it with get_code_session id=<session_id> turn=<turn_idx>, or session_summary session_id=<session_id>. Records carry links to their sources when known: sha (the commit the session was on), paths (files it names, up to 5), ref_url (the ref's forge page). Open them directly; they locate sources, they do not report current state. Results are dated records of what sessions did, not the current state of a PR or issue; check that live.
Inputs: query (required), days, kind, path, +7 more.
search_conversationsA
Search the user's synced conversations AND coding-agent sessions by keyword and semantic similarity — results are tagged source_type (chat/code) and, when a matching chunk exists, resolve to the specific message span inside the conversation rather than just its title. To find a chat or session from a specific time, pass since (or days): e.g. yesterday's chat about X → query = X, since = yesterday's date. To browse recent activity with no query, use list_recent_conversations. Hits are raw text as said, not extracted, checked or versioned: true when said, not current truth; for decisions, learnings and outcomes use memory_search. Results are dated records of what sessions did, not the current state of a PR or issue; check that live.
Inputs: query (required), days, limit, scope, +1 more.
session_summaryA
Get one coding session's header (repo, branch, turns, models, files touched) and its JOURNEY: threads in order from the first prompt, each with its records (outcomes first) and files touched in that range. Use it for the short story of a session (what it set out to do and what it found); use get_code_session when you need the actual turns, e.g. the exact words around a memory_search record. Results are dated records of what sessions did, not the current state of a PR or issue; check that live.
Inputs: last, repo, session_id, recall_token.
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 retrieval tools are mostly distinct: memory_search targets extracted topic memory, memory_recall targets repo/path memory, search_conversations targets raw keyword/semantic text, and list_recent_conversations is for browsing recent sessions. Some overlap remains among the three search/recall tools, but the descriptions provide clear selection guidance.
All names use snake_case and are generally readable, with mostly verb_noun patterns like get_code_session, list_code_projects, and search_conversations. Minor deviations exist, such as memory_search/recall/resolve using an object-first grouping and session_summary being noun-only, but the conventions are still predictable.
Nine tools is well-scoped for a memory and conversation retrieval server. Each tool maps to a meaningful operation: listing, searching, recalling, resolving, and retrieving sessions or conversations.
The surface covers the core lifecycle of browsing conversations and coding sessions, searching raw text, finding extracted memories, and resolving blockers. Minor gaps exist, such as no explicit browse/list operation for memory records or dedicated project-scoped session listing, but agents can work around these with existing filters.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Shared, scoped, reviewable team memory for AI coding agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP-native, local-first memory for coding agents that turns real sessions into reusable decisions, gotchas, and domain knowledge.17136 PyPI7MIT
- AlicenseAqualityBmaintenanceLocal-first AI PKM memory server for coding conversations. Imports Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot chats into notes, semantic search, tag graphs, Markdown exports, and MCP memory tools.7121 npm62Apache 2.0
- AlicenseNot gradedqualityBmaintenanceLocal-first memory daemon for AI coding agents that captures session transcripts, distills typed memories (decisions, facts, lessons, commands, todos), and serves them via hybrid search through MCP tools.40 npmMIT
- 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