openmembrane: Instructions file for Codex

AGENTS.md

Project context for AI coding tools working on the OpenMembrane codebase.

Project Overview

OpenMembrane is a local-first, private, tool-agnostic memory membrane for AI coding tools. It autonomously extracts durable project knowledge from session transcripts, filters out secrets and noise, and persists approved memories — without any manual effort from the user.

Architecture

Pipeline

session transcript
  -> secret redaction
  -> memory extraction
  -> classification
  -> policy / safety / noise filtering
  -> deduplication
  -> conflict detection
  -> action recommendation (auto_save / ask_user / reject)
  -> memory store or pending candidate queue

Monorepo Structure

packages/core/       — Domain types, extraction interface, pipeline orchestration,
                       classification, policy, deduplication, conflict detection
packages/storage/    — Local JSON persistence (memories, pending candidates, audit, diagnostics)
packages/exporters/  — Static fallback file generation (AGENTS.md, CLAUDE.md, etc.)
packages/shared/     — IDs, time helpers, generic result types
apps/mcp-server/     — MCP server (tool registration, validation, error responses)
tests/               — All test files (unit and integration)

Packages are imported via path aliases: @openmembrane/core, @openmembrane/storage, @openmembrane/exporters, @openmembrane/shared.

Extractor Boundary

LLM integration stays behind an interface. The core must not hardwire a single provider.

interface MemoryExtractor {
  extract(input: SessionInput): Promise<MemoryCandidate[]>;
}

TypeScript Conventions

• Target: ES2022, ESM ("type": "module" in package.json)
• Strict mode with noUncheckedIndexedAccess and exactOptionalPropertyTypes enabled
• Use type imports for type-only references (import type { ... })
• No enums — use as const arrays with derived union types (see MemoryCandidate.ts for examples)
• Prefer explicit return types on exported functions
• Use readonly for class fields that are set once in the constructor