Skip to main content
Glama

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.

License: MIT membral MCP server – quality and maintenance score on Glama

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 4

In. 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 run membral 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.

  1. Pick an extraction model by putting one choice in ~/.membral/local/.env (mkdir -p ~/.membral/local first):

    • Claude subscription: CLAUDE_CODE_OAUTH_TOKEN=<from claude setup-token>. When claude is on your PATH and no other choice is set, up selects the claude-code provider for you.

    • API key: OPENAI_API_KEY=... (or OPENROUTER_API_KEY)

    • Ollama: a 7B+ model such as qwen2.5:7b, run with OLLAMA_CONTEXT_LENGTH=16384 ollama serve

  2. 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 ollama to use Ollama's nomic-embed-text instead of the bundled model.

  3. Check it: npx membral local status (it prints an Embeddings: ... 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.

  1. npm run build --workspace=@membral/extension (targets http://localhost:3000; for another port build with VITE_CLOUD_URL=http://localhost:<port>, or save a Server URL in the options page, where Chrome asks permission).

  2. In chrome://extensions, turn on Developer mode, choose Load unpacked, pick packages/extension/dist.

  3. In the options page, paste the API key npx membral local up printed (it starts lls_) 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> | down runs the stack (down --wipe deletes the data); npx membral local reembed moves stored vectors to a new embedding model.

  • membral setup, login (default http://localhost:3000), use, sessions, import <export.json> and status.

  • membral --help lists every command. npm run smoke checks 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 tools
get_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.

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

    A4.2/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Local-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.
      7
      121 npm
      62
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Local-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 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Persistent 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.
      22
      4
      MIT