Remnic (formerly Engram)
Persistent, private, local-first memory for AI agents.
Open source, MIT licensed. https://github.com/joshuaswarren/remnic

All data stays on the user's machine as plain markdown files with YAML
frontmatter. No cloud services, no external databases, no subscriptions.

Works with OpenClaw, Claude Code, Codex CLI, Hermes Agent, Replit, Cursor,
and any MCP-compatible client. Tell one agent a preference — every agent
remembers it.

ARCHITECTURE

TypeScript ESM monorepo. pnpm workspaces. Node 22+.

Packages:
  @remnic/core            Engine (orchestrator, storage, search, extraction,
                          graph, trust zones, LCM). Framework-agnostic.
  @remnic/cli             Standalone CLI binary, 20+ commands.
  @remnic/server          HTTP + MCP server with multi-token auth, daemon mode.
  @remnic/bench           Latency benchmarks with CI regression gates.
  @remnic/plugin-openclaw OpenClaw adapter (embedded or delegate mode).
  @remnic/plugin-codex    Codex CLI adapter (hooks + MCP + memory extension).
  @remnic/hermes-provider TypeScript HTTP client for remote Remnic instances.
  @remnic/import-supermemory Optional Supermemory JSON importer for
                          `remnic import --adapter supermemory`.
  remnic-hermes           Python PyPI package, MemoryProvider for Hermes Agent.

OpenClaw adapter note:
  The OpenClaw plugin registers `before_prompt_build` with Remnic's
  `initGateTimeoutMs` as the per-hook timeout on SDKs that support hook
  options. The same config bounds Remnic's internal cold-start init gate for
  recall and day summaries. Default: 30000ms; accepted range: 1000-120000ms.

Three-phase flow:
  1. Recall   Before each agent turn, inject relevant memories into context.
  2. Buffer   After each turn, accumulate content until a trigger fires.
  3. Extract  Periodically, extract structured memories via an LLM call.

Storage: plain markdown + YAML frontmatter. Categories include fact,
decision, preference, correction, relationship, principle, commitment,
moment, skill, rule, entity, and more.

Search: hybrid BM25 + vector + reranking via QMD. Six backend options:
QMD (default), Orama (embedded JS), LanceDB (embedded native Arrow),
Meilisearch (server), Remote (HTTP REST), Noop (extraction only).

KEY FEATURES

Core (enabled by default):
  - Automatic extraction and recall injection
  - Entity tracking and relationship graph
  - Memory lifecycle (active -> validated -> stale -> archived)
  - Episode/note model (time-specific events vs stable beliefs)
  - Importance-gated extraction (trivial content never hits disk)
  - Inline source attribution (provenance tags in fact body)

Lossless Context Management (LCM):
  Proactive session archive into local SQLite + hierarchical summary DAG.
  When context gets compacted, LCM injects compressed history back into
  recall. Three-level summarization with guaranteed convergence. Full-text
  search over archived messages. Zero data loss.

Parallel Specialized Retrieval:
  Three agents run in parallel (latency = max, not sum):
    DirectFact  Scans entity filenames for keyword overlap (<5ms).
    Contextual  Existing hybrid BM25+vector search.
    Temporal    Reads date index with recency decay scoring (<10ms).
  Zero additional LLM cost. Graceful per-agent degradation.

Semantic Consolidation:
  Finds clusters of similar memories via token overlap, synthesizes a
  canonical version via LLM, archives originals. Conservative threshold
  (80%+), corrections and commitments excluded by default.

Trust Zones:
  Quarantine -> working -> trusted tiers with promotion rules and
  poisoning defense. Provenance tracking and corroboration scoring.

Extraction Judge (issue #376):
  LLM-as-judge post-extraction durability filter. Shadow mode available
  for calibration before enabling gating.

Semantic Chunking (issue #368):
  Topic-boundary detection via sentence embeddings and cosine similarity
  with smoothing. Alternative to recursive chunking.

Page Versioning (issue #371):
  Snapshot-based history for memory files. Every overwrite saves a
  numbered snapshot. List, inspect, diff, and revert via CLI or API.

OAI-mem-citation Blocks (issue #379):
  Recall responses emit <oai-mem-citation> blocks matching the Codex
  citation format for memory attribution and usage tracking.

Memory Extension Publisher Contract (issue #381):
  Pluggable contract for installing host-specific instruction files into
  any AI agent host's extension directory. Generalizes Codex extension
  pattern.

Memory Extension Discovery (issue #382):
  Third-party memory extensions provide structured instructions that
  influence consolidation, auto-discovered from extension directories.

MECE Taxonomy (issue #366):
  Mutually Exclusive, Collectively Exhaustive knowledge directory with
  resolver decision tree for deterministic memory categorization.

Enrichment Pipeline (issue #365):
  Importance-tiered API spend for entity enrichment from external sources
  with a provider registry.

Binary Lifecycle (issue #367):
  Three-stage pipeline (mirror, redirect, clean) for binary files in the
  memory directory with configurable storage backends.

Codex Marketplace (issue #418):
  Install via: codex marketplace add joshuaswarren/remnic

Memory OS (progressive opt-in):
  Memory boxes, graph recall, compounding (weekly synthesis), shared
  context (cross-agent), identity continuity, hot/cold tiering, native
  knowledge search, behavior loop tuning.

Advanced (opt-in):
  Objective-state recall, causal trajectories, harmonic retrieval,
  verified recall, semantic rule promotion, creation memory, commitment
  lifecycle.

BUILD / TEST / DEVELOP

  Build:        pnpm run build
  Test:         npm run test        (node:test with tsx, 672+ tests)
  Typecheck:    pnpm run check-types
  Quality gate: npm run preflight:quick
  Eval suite:   npm run eval:run

ACCESS LAYER

HTTP API:
  Most routes under /engram/v1/... (v1.x compatibility window).
  Bearer-token auth, binds to loopback by default.
  Routes: health, recall, recall/explain, memories (CRUD), entities,
  observe, lcm/search, lcm/status, trust-zones/status, trust-zones/records,
  trust-zones/promote, review-queue, maintenance, suggestions,
  review-disposition.
  Exception: POST /v1/citations/observed (no /engram prefix).

MCP tools:
  Exposed via stdio and HTTP transports. 14+ tools covering recall, store,
  entity lookup, memory search, LCM expansion, trust zone inspection, and
  observation.

Standalone CLI (20+ commands):
  init, status, query, doctor, config, daemon, tree, onboard, curate,
  review, sync, dedup, connectors, space, benchmark, versions, taxonomy,
  enrich, binary.

Operator UI:
  http://127.0.0.1:4318/engram/ui/

DOCUMENTATION

  README.md                    Full installation guide, feature list, architecture
  CLAUDE.md                    Project instructions and privacy policy
  AGENTS.md                    Agent guide with 43 review prevention patterns
  docs/config-reference.md     90+ configuration properties
  docs/api.md                  HTTP, MCP, and CLI reference
  docs/architecture/           Per-feature architecture docs
  docs/guides/                 Standalone, Codex, Claude Code, local LLM, etc.
  docs/guides/openclaw-engram-to-remnic.md
                               Legacy OpenClaw Engram -> Remnic migration:
                               package rename, config keys, backups, patches
  docs/getting-started.md      Quick start
  docs/operations.md           Operations guide
  docs/search-backends.md      Search backend comparison
  docs/namespaces.md           Namespace isolation
  docs/import-export.md        Data portability

CONFIGURATION

Config resolved from: REMNIC_CONFIG_PATH env var -> ./remnic.config.json ->
~/.config/remnic/config.json. Presets: conservative, balanced, research-max,
local-llm-heavy. 90+ properties. LLM routing: OpenAI API, local LLM (Ollama,
LM Studio), or gateway model chain with multi-provider fallback.

QUICK START (STANDALONE)

  npm install -g @remnic/cli
  remnic init
  export OPENAI_API_KEY=sk-...
  export REMNIC_AUTH_TOKEN=$(openssl rand -hex 32)
  remnic daemon start
  remnic status
  remnic query "hello" --explain

QUICK START (OPENCLAW)

  openclaw plugins install clawhub:@remnic/plugin-openclaw
  remnic openclaw install
  launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
  remnic doctor

  OpenClaw 2026.5.2+ resolves bare plugin package names through ClawHub before
  npm fallback. Remnic is published on ClawHub as @remnic/plugin-openclaw; for
  npm-only fallback or rollback versions, use the explicit npm source prefix
  npm:@remnic/plugin-openclaw@<version>.

  ClawHub publish note: publish @remnic/plugin-openclaw from the built
  ClawPack/npm tarball, not from the raw GitHub source folder. Run
  pnpm --filter @remnic/plugin-openclaw build, pnpm run verify:openclaw-clawpack,
  clawhub package pack packages/plugin-openclaw, then clawhub package publish
  the generated remnic-plugin-openclaw-<version>.tgz with source metadata.

OPENCLAW PLUGIN COMPATIBILITY

  The OpenClaw adapter keeps both manifest compatibility surfaces:
  supports: legacy/current slot, active-memory, heartbeat, command, and reset
  routing for OpenClaw 2026.4-era runtimes.
  setup.providers must stay omitted because Remnic does not own host provider
  ids. providerAuthEnvVars remains for older OpenClaw builds during the
  upstream deprecation window. Keep it synchronized with providerAuthChoices
  and configSchema.openaiApiKey.
  contracts.tools: required by OpenClaw 2026.5+ plugin descriptor planning and
  tool ownership validation. Add every Remnic-owned registerTool name here when
  adding OpenClaw tools, including conditional LCM aliases.

  Source of truth: packages/plugin-openclaw/openclaw.plugin.json.
  Synced copies: openclaw.plugin.json and
  packages/shim-openclaw-engram/openclaw.plugin.json.
  Guard test: tests/openclaw-plugin-runtime-surfaces.test.ts.

LEGACY OPENCLAW ENGRAM MIGRATION

  Use this for @joshuaswarren/openclaw-engram 9.2.x -> @remnic/plugin-openclaw.
  Canonical OpenClaw plugin id: openclaw-remnic.
  Legacy plugin id: openclaw-engram.
  Do not use remnic-workspace as an OpenClaw plugin id; it is the npm workspace
  root package name, not the OpenClaw runtime id.

  remnic openclaw migrate-engram --yes

  This backs up openclaw.json, backs up the legacy openclaw-engram extension
  directory, installs @remnic/plugin-openclaw into openclaw-remnic, writes
  plugins.entries["openclaw-remnic"], sets plugins.slots.memory to
  "openclaw-remnic", and preserves the memoryDir.

CONNECTING OTHER AGENTS

  remnic connectors install claude-code
  remnic connectors install codex-cli
  remnic connectors install replit
  pip install remnic-hermes
