Skip to main content
Glama
README.md
# 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](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![membral MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/surajtripathy07/membral/badges/score.svg)](https://glama.ai/mcp/servers/surajtripathy07/membral)

## How it fits together

```mermaid
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.

## 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](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](docs/SELF-HOSTING.md#claude-code-plugin)).

## 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](docs/SELF-HOSTING.md) covers the stack in depth. [CONTRIBUTING.md](CONTRIBUTING.md) goes
from clone to green gate to PR. [docs/COMPARISON.md](docs/COMPARISON.md) compares Membral with other ways of giving an agent memory.

## License

MIT, see [LICENSE](LICENSE). Source: [github.com/surajtripathy07/membral](https://github.com/surajtripathy07/membral).

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