OpenMemBrain
OpenMemBrain é a membrana inteligente para a memória de codificação de IA. Ela lê e aprende autonomamente com suas sessões de codificação — você nunca precisa dizer a ela o que salvar. Ela absorve seletivamente o conhecimento do projeto, bloqueia segredos, filtra ruídos, resolve conflitos e persiste apenas o que importa.
Documentação
OpenMembrane
OpenMembrane is the intelligent membrane for AI coding memory. It autonomously reads and learns from your coding sessions — you never have to tell it what to save. It selectively absorbs project knowledge, blocks secrets, filters noise, resolves conflicts, and persists only what matters.
No manual effort. No data leaves your machine unless you choose it. Safe, private, and trustworthy by design.
Table of Contents
-
Zero-effort — learns from sessions automatically, no commands or prompts needed
-
Secure by default — secrets are detected and rejected before they ever reach storage
-
Self-managing — deduplicates, resolves conflicts, and filters noise on its own
-
Local Private by default — memory is stored locally in git-ignored
.openmembrane/ -
Tool-agnostic — dedicated adapters for OpenCode, Claude Code, Codex and VS Code/Copilot, plus MCP for Cursor, Claude Desktop and others
Installation
Install and run the MCP server with npx (requires Node.js >= 18):
npx openmembrane
Or install globally:
npm install -g openmembrane
openmembrane
No cloud account is required for the default Local Private mode, which stores
memory locally in git-ignored .openmembrane/.
The local daemon has explicit lifecycle commands:
openmembrane serve # foreground
openmembrane start # detached
openmembrane status
openmembrane stop
Bare openmembrane and openmembrane mcp both launch MCP stdio.
CLI data commands and the review UI use the authenticated local daemon.
Run openmembrane start first; these surfaces report an error if the daemon
is unavailable and never fall back to opening stores themselves. MCP uses
the same client and auto-starts the daemon on the first tool call, then
reuses it across calls and sessions. Listing tools does not start it. See
Daemon Protocol for transport, authentication,
and per-project request settings.
CLI and local review
Run these commands from your project directory. --project <id> overrides
OPENMEMBRANE_PROJECT_ID; OPENMEMBRANE_HOME selects project storage, not
the per-user daemon endpoint.
openmembrane ingest --file session.txt --tool codex
openmembrane ingest --stdin --tool claude-code --session-id session-123
openmembrane context --query "deployment rules" --output markdown
openmembrane candidates list --output json
openmembrane candidates approve <id>
openmembrane candidates reject <id> --reason "Obsolete"
openmembrane candidates approve-all
openmembrane candidates reject-all
openmembrane memory update <id> --content "Updated project rule"
openmembrane memory supersede <id> --reason "Replaced" --replacement-id <new-id>
openmembrane memory stale --stale-after-months 6
openmembrane export --targets agents,claude --preview
openmembrane export --targets agents,claude --output-dir generated
openmembrane diagnostics --severity warning --limit 100
openmembrane audit --limit 100
openmembrane team configure --owner my-team --repo private-memory
openmembrane team status
All data commands support --output text|json|markdown. Ingest defaults to
JSON for compatibility; the others default to text. openmembrane --help
lists command-specific filters and options. Bulk approval skips candidates
that cannot be approved, including secrets, and reports each skipped ID.
GitHub Team mutations report publication/retry state rather than implying
that an unmerged proposal is already active.
From this repository, npm run review-ui -- --no-open starts the loopback
review UI. The Overview identifies the current project and shows proposals
awaiting review and active memories not updated in six months. Unavailable data
is reported separately from an empty queue; use Try again or Refresh view
to retry. Overview and Review queue share the navigation badge; only the latest
queue request may update its count or unavailable state, including after a review
decision. A memory edit, retirement, or graph review that finishes while Overview
is visible also refreshes its attention counts.
Open the Review queue to read each proposal, its explanation (when available), sensitivity, and suggested action. Approve useful knowledge or reject a proposal with an optional reason. Secret proposals cannot be approved. Bulk review actions apply to the entire queue and ask for confirmation; bulk approval skips ineligible proposals. GitHub Team approval can still require publication and merge before the knowledge becomes active. Approval results distinguish locally saved memories, published team proposals, scheduled/deferred publication retries, and terminal publication failures. Publication failures remain visible until dismissed; terminal failures include the rejection reason and explicitly state that no retry is scheduled. After bulk approval, expand Bulk review result for every memory outcome and skipped-proposal reason. Terminal publication failures do not count as approved.
Saved memories shows full memory text with search and type/scope filters (up to 200 matches). Select Review or edit to change a memory; expand Retire this memory to supersede it and optionally identify its replacement. Older memories defaults to six months and lets you change that interval; age is a review prompt, not proof that a memory is incorrect. Knowledge graph, Activity history, and Diagnostics retain exploration and troubleshooting tools. The graph provides 2D and list views with optional 3D exploration; all modes share graph data, filters, selection, and inspector state. Activity and diagnostics show the latest 100 matching records. Export files supports preview and write; preview never writes files, and confidential memories are excluded unless you explicitly opt in. Refreshing Activity history, Diagnostics, or Older memories ignores responses from older requests, including obsolete errors, so the latest request wins.
To preview the graph without connecting a daemon or project memory store, run
npm run preview:graph -- 61327 and open http://127.0.0.1:61327/. This
loopback-only fixture contains 500 synthetic nodes and 1,000 relationships;
graph mutations are disabled.
Configuring Your AI Tool
Pick the integration for your tool. OpenCode, Claude Code and Codex adapters
capture sessions through the local daemon; retrieval and stored-memory egress
to the model provider require the opt-ins described in each guide (Claude Code
and Codex also need separate MCP setup for retrieval). VS Code cannot capture
ordinary Copilot chats automatically: use explicit export capture, or opt-in
auto-save for the extension's own participant exchanges. MCP is the fallback for
tools without an adapter. The CLI is required for every integration except VS
Code, whose extension bundles it (npm install -g openmembrane).
| Tool | Integration | Setup guide |
|---|---|---|
| OpenCode | @openmembrane/adapter-opencode plugin | OpenCode setup |
| Claude Code | @openmembrane/adapter-claude-code hooks | Claude Code setup |
| VS Code / GitHub Copilot | VS Code extension | VS Code setup |
| Codex | @openmembrane/adapter-codex hooks | Codex setup |
| Cursor | MCP config (fallback) | Cursor setup |
| Claude Desktop | MCP config (fallback) | below |
The MCP server runs over stdio and auto-starts the daemon on its first tool call. Add it to your AI tool's MCP configuration:
Claude Desktop
Edit claude_desktop_config.json:
{
"mcpServers": {
"openmembrane": {
"command": "npx",
"args": ["openmembrane"]
}
}
}
Claude Code
claude mcp add openmembrane -- npx openmembrane
Codex
For automatic session capture with native hooks and startup retrieval instructions, follow Codex setup:
npm install -g openmembrane
npx @openmembrane/adapter-codex install
Restart Codex and review/trust the hook with /hooks. MCP retrieval is
configured separately and requires explicit permission for stored-memory egress.
VS Code / GitHub Copilot
The VS Code extension bundles the CLI,
starts the local daemon and registers MCP retrieval without manual configuration.
It also adds @openmembrane /rules, /recall, /review, candidate review,
export and diagnostics commands, and explicit chat export capture. Stable
VS Code APIs do not expose all Copilot sessions; opt-in auto-save covers only
the extension's own participant exchanges.
See VS Code setup for VSIX installation.
Alternatively, add to .vscode/mcp.json in your project:
{
"servers": {
"openmembrane": {
"command": "npx",
"args": ["openmembrane"]
}
}
}
Cursor
Add to .cursor/mcp.json in your project:
{
"mcpServers": {
"openmembrane": {
"command": "npx",
"args": ["openmembrane"]
}
}
}
OpenCode
For automatic session capture and opt-in context injection, follow OpenCode plugin setup. It covers installation, explicit consent to send stored memory to OpenCode's model provider, extraction configuration, and uninstall instructions.
For optional MCP tools, add to ~/.config/opencode/opencode.json:
{
"mcp": {
"openmembrane": {
"type": "local",
"command": ["npx", "-y", "openmembrane"]
}
}
}
See .opencode/INSTALL.md for detailed setup including
global instructions and development-from-source configuration.
Automatic Memory Capture
Adding the MCP server gives your AI tool access to OpenMembrane's tools. To ensure the AI uses them automatically — loading project memory at session start and saving durable knowledge as it's discovered — add a global instruction file.
Create ~/.config/openmembrane/instructions.md with instructions for the AI to:
- Call
get_project_rules,get_relevant_context, andlist_memory_candidatesat the start of each session. - Use
approve_memory_candidateorreject_memory_candidateafter the developer decides what to retain. - Call
rememberproactively when durable knowledge is discovered, providing structured content and a type (e.g.,coding_rule,known_gotcha,architecture_decision). No API key needed.
Then wire the file into your tool's global configuration:
| Platform | Global instruction mechanism |
|---|---|
| OpenCode | "instructions": ["~/.config/openmembrane/instructions.md"] in ~/.config/opencode/opencode.json |
| Claude Code | Append to ~/.claude/CLAUDE.md |
| Codex | Adapter-managed section in ~/.codex/AGENTS.md |
| Cursor | Add to Rules for AI in Cursor Settings |
| VS Code / Copilot | Create ~/.copilot/instructions/openmembrane.instructions.md with applyTo: "**" |
See the platform-specific setup guides in docs/setup/ for
detailed instructions.
Alternatively, run openmembrane export from any project to generate
per-project instruction files (AGENTS.md, CLAUDE.md, etc.) that include both
usage instructions and stored memories.
Deployment Modes
OpenMembrane ships Local Private mode by default and GitHub Team mode for shared memory through a dedicated private repository. Self-Hosted Team and Managed Team are planned. Static exported files are separate from team sync; see Deployment Modes for the approved-memory boundary and GitHub pull-request workflow.
Environment Variables
By default, local memory is stored in .openmembrane under the current working directory. Override this with:
OPENMEMBRANE_HOME: directory for local JSON memory stores.OPENMEMBRANE_PROJECT_ID: default project id when a tool call does not passprojectId.
MCP Tools
remember— save structured memory directly. Provide content, type, and optional scope/tags. No API key needed. Supports single and batch mode.get_project_rules— retrieve project rules and conventions for the current scope.get_relevant_context— find memories relevant to a natural language query.search_memory— search saved memories by query, scope, type, or tags.list_memory_candidates— list pending memory candidates awaiting approval.approve_memory_candidate— approve a pending candidate to save it as memory.reject_memory_candidate— reject a pending candidate with an optional reason.
These are the seven mid-session MCP tools. Transcript ingestion, bulk review, memory maintenance, export, diagnostics, audit, and team configuration are user operations available through the CLI and review UI. See MCP migration for each removed tool's replacement.
Architecture
OpenMembrane supports two paths for saving memory:
-
remember(primary): The AI tool callsrememberdirectly with structured content and type. No server-side LLM needed. Memories go through the full pipeline (secret detection, policy filtering, deduplication) and are auto-saved. -
openmembrane ingest(secondary): An adapter submits a full session transcript through the CLI or daemon ingestion endpoint for server-side LLM extraction. Requires an explicitly configured daemon extractor (OpenAI or compatible provider).
remember tool CLI / daemon ingestion
| |
v v
processStructured() SessionIngestor
| -> SecretDetector redaction
v -> MemoryExtractor interface
MemoryClassifier -> MemoryClassifier
-> PolicyEngine -> PolicyEngine
-> Deduplicator -> Deduplicator
-> ConflictDetector -> ConflictDetector
-> ActionRecommender -> ActionRecommender
-> MemoryStore or PendingCandidateStore
Package responsibilities:
packages/core: domain types, extraction interface, policy checks, classification, deduplication, conflict detection, and pipeline orchestration.packages/storage: local JSON persistence for saved memory, pending approvals, and audit events.packages/service: project-scoped operations, storage lifecycle, and GitHub Team synchronization owned by the daemon.packages/protocol: versioned daemon HTTP schemas and shared endpoint resolution.packages/client: authenticated local-daemon client used by MCP, CLI, review UI, and adapters.packages/exporters: static fallback file generation for AI tools that read project instruction files.packages/shared: small runtime helpers for IDs, time, and result types.apps/mcp-server: local MCP server exposing saved memory and approval workflows to AI tools.apps/daemon: authenticated per-user HTTP daemon with project-scoped stores and CLI lifecycle management.
Provider-specific LLM calls are intentionally kept out of the core. The boundary is:
interface MemoryExtractor {
extract(input: SessionInput): Promise<MemoryCandidate[]>;
}
The MockMemoryExtractor is used for deterministic testing. The LlmMemoryExtractor supports OpenAI and any compatible API endpoint (via baseUrl).
Diagnostics And Errors
OpenMembrane distinguishes audit history from diagnostics:
- Audit events describe normal memory activity, such as session ingestion, candidate extraction, saved memory, queued candidates, and rejected candidates.
- Diagnostics describe operational problems, such as validation errors, missing candidates, invalid local JSON stores, unsafe approval attempts, and export failures.
MCP tools return safe user-facing error payloads with a diagnosticId, preserving
the daemon's ID and safe message. Inspect project diagnostics with
openmembrane diagnostics or the review UI, and daemon failures in the local
daemon log. Client-side failures are correlated on MCP stderr, never stdout.
Static Fallback Files
Static exporters can generate:
AGENTS.mdCLAUDE.md.github/copilot-instructions.md.cursor/rules/openmembrane.mdcdocs/ai/project-memory.md
These files are compatibility fallbacks for tools that cannot retrieve memory through MCP. By default, exporters omit confidential memories because these files may be committed to source control. Callers must explicitly opt in to include confidential memory.
Development
git clone https://github.com/mohamadalhusseinie/openmembrane.git
cd openmembrane
npm install
Run the MCP server locally (from source via tsx):
npm run mcp:stdio
Run tests and type checking:
npm test # vitest
npm run typecheck # tsc --noEmit
npm run check # both
Build the publishable bundle:
npm run build
Documentation
- Setup guides — per-tool installation for OpenCode, Claude Code, Codex, VS Code/Copilot and Cursor
- Daemon Protocol — transport, authentication and lifecycle
- Architecture — pipeline design, type schemas, MCP tool surface, package dependencies
- Security and Privacy — secret handling, data storage rules, LLM usage policy
- Product Vision — product thesis, UX workflow, memory quality criteria
- Deployment Modes — current Local Private and GitHub Team modes, plus planned team modes
- Roadmap — phased delivery plan for Local Private, GitHub Team, and planned team modes
- Contributing — setup, development workflow, PR guidelines