# 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

- [Installation](#installation)
- [Configuring Your AI Tool](#configuring-your-ai-tool)
  - [Claude Desktop](#claude-desktop)
  - [Claude Code](#claude-code)
  - [VS Code / GitHub Copilot](#vs-code--github-copilot)
  - [Cursor](#cursor)
  - [OpenCode](#opencode)
- [Automatic Memory Capture](#automatic-memory-capture)
- [Deployment Modes](#deployment-modes)
- [Environment Variables](#environment-variables)
- [MCP Tools](#mcp-tools)
- [Architecture](#architecture)
- [Diagnostics And Errors](#diagnostics-and-errors)
- [Static Fallback Files](#static-fallback-files)
- [Development](#development)
- [Documentation](#documentation)

- **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** — works with any AI coding tool via MCP (Claude, Copilot, Cursor, OpenCode, and more)

## Installation

Install and run the MCP server with npx (requires Node.js >= 18):

```sh
npx openmembrane
```

Or install globally:

```sh
npm install -g openmembrane
openmembrane
```

No cloud account is required for the default Local Private mode, which stores
memory locally in git-ignored `.openmembrane/`.

## Configuring Your AI Tool

OpenMembrane runs as an MCP server over stdio. Add it to your AI tool's MCP configuration:

### Claude Desktop

Edit `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}
```

### Claude Code

```sh
claude mcp add openmembrane -- npx openmembrane
```

### VS Code / GitHub Copilot

Add to `.vscode/mcp.json` in your project:

```json
{
  "servers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}
```

### OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "openmembrane": {
      "type": "local",
      "command": ["npx", "-y", "openmembrane"]
    }
  }
}
```

See [`.opencode/INSTALL.md`](.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`, and `list_memory_candidates`
  at the start of each session.
- Call `remember` proactively 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` |
| **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/`](docs/setup/) for
detailed instructions.

Alternatively, run `export_static_memory_files` in 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](docs/deployment-modes.md#local-private)
by default and [GitHub Team mode](docs/deployment-modes.md#github-team) 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](docs/deployment-modes.md) 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 pass `projectId`.

## MCP Tools

- `remember` — save structured memory directly. Provide content, type, and optional scope/tags. No API key needed. Supports single and batch mode.
- `propose_memory_from_session` — submit a session transcript or summary for server-side LLM extraction. Requires a configured extractor. Useful for automation adapters.
- `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.
- `approve_all_candidates` — approve all pending candidates at once.
- `reject_memory_candidate` — reject a pending candidate with an optional reason.
- `reject_all_candidates` — reject all pending candidates at once.
- `update_memory` — update the content, type, scope, or tags of a saved memory.
- `supersede_memory` — mark a memory as superseded, optionally linking a replacement.
- `review_stale_memories` — list memories older than a threshold (default: 6 months).
- `export_static_memory_files` — generate static instruction files (AGENTS.md, CLAUDE.md, etc.).
- `get_diagnostics` — retrieve diagnostic events filtered by severity or code.
- `list_audit_log` — retrieve recent audit events.

## Architecture

OpenMembrane supports two paths for saving memory:

1. **`remember` (primary):** The AI tool calls `remember` directly 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.

2. **`propose_memory_from_session` (secondary):** An adapter or AI tool submits a full session transcript for server-side LLM extraction. Requires a configured extractor (OpenAI or compatible provider).

```text
remember tool                          propose_memory_from_session
  |                                      |
  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/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.

Provider-specific LLM calls are intentionally kept out of the core. The boundary is:

```ts
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`. The detailed diagnostic can be inspected through `get_diagnostics` without exposing raw transcripts or secrets.

## Static Fallback Files

Static exporters can generate:

- `AGENTS.md`
- `CLAUDE.md`
- `.github/copilot-instructions.md`
- `.cursor/rules/openmembrane.mdc`
- `docs/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

```sh
git clone https://github.com/mohamadalhusseinie/openmembrane.git
cd openmembrane
npm install
```

Run the MCP server locally (from source via tsx):

```sh
npm run mcp:stdio
```

Run tests and type checking:

```sh
npm test          # vitest
npm run typecheck # tsc --noEmit
npm run check     # both
```

Build the publishable bundle:

```sh
npm run build
```

## Documentation

- [Architecture](docs/architecture.md) — pipeline design, type schemas, MCP tool surface, package dependencies
- [Security and Privacy](docs/security-and-privacy.md) — secret handling, data storage rules, LLM usage policy
- [Product Vision](docs/product-vision.md) — product thesis, UX workflow, memory quality criteria
- [Deployment Modes](docs/deployment-modes.md) — current Local Private and GitHub Team modes, plus planned team modes
- [Roadmap](docs/roadmap.md) — phased delivery plan for Local Private, GitHub Team, and planned team modes
- [Contributing](CONTRIBUTING.md) — setup, development workflow, PR guidelines