remnic

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

One memory store, every agent. Tell one tool a preference and every other
tool remembers it: OpenClaw, Claude Code, Codex CLI, Cursor, ChatGPT
(developer mode), Hermes, Replit, Pi, omp, and any MCP client.

All data stays on the user's machine as plain markdown files with YAML
frontmatter. No cloud service, no external database, no subscription. The
canonical store is a directory you own and can read, grep, and back up.

Remnic is universal/standalone-first (`npm install -g @remnic/cli`), with
OpenClaw as the deepest native integration. "Engram" survives only as an
intentional compatibility surface (HTTP `/engram/v1/...`, the `openclaw
engram` command namespace, the `openclaw-engram` legacy plugin id, `engram`
bin aliases, `ENGRAM_*` env fallbacks, `X-Engram-*` headers). Prefer the
`remnic` equivalent wherever one exists.


ARCHITECTURE

TypeScript ESM monorepo. pnpm workspaces (pnpm 10.x). Node >= 22.12.
27 package directories: 25 published to npm, one private dashboard, one
PyPI-only Python plugin.

Published npm packages:
  @remnic/core             Memory engine: orchestrator, storage, extraction,
                           search, entity graph, trust zones, LCM.
                           Framework-agnostic; every adapter builds on it.
  @remnic/cli              Standalone `remnic` CLI (35 top-level commands).
                           Ships `remnic` and legacy `engram` bins.
  @remnic/server           Standalone HTTP + MCP server. Multi-token auth,
                           daemon mode, OAuth facade. Ships `remnic-server`
                           and legacy `engram-server` bins.
  @remnic/coding-graph     web-tree-sitter symbol extraction + SQLite code
                           knowledge graph. Optional companion of core.
  @remnic/belief-ledger    Belief and prediction ledger on Remnic primitives.
  @remnic/bench            Published memory-benchmark harness + CI regression
                           gates.
  @remnic/plugin-openclaw  OpenClaw memory-slot adapter with bundled core
                           runtime. Deepest integration.
  @remnic/plugin-codex     Codex CLI plugin (hooks + MCP + memory extension).
  @remnic/plugin-claude-code  Claude Code plugin (hooks, skills, agents, MCP).
                           Files-only, zero dependencies.
  @remnic/plugin-pi        Remnic memory extension for the Pi Coding Agent.
  @remnic/replit           Replit Agent MCP connector.
  @remnic/connector-limitless  Limitless Pendant wearable connector.
  @remnic/connector-bee    Bee wearable connector.
  @remnic/connector-omi    Omi necklace connector.
  @remnic/connector-weclone  OpenAI-compatible proxy adding Remnic memory to
                           WeClone avatars. Ships `remnic-weclone-proxy`.
  @remnic/export-weclone   Export memories as WeClone/Alpaca fine-tuning sets.
  @remnic/hermes-provider  Typed TypeScript HTTP client for the memory API.
  @remnic/import-chatgpt   ChatGPT data-export importer.
  @remnic/import-claude    Claude.ai data-export importer.
  @remnic/import-gemini    Google Takeout Gemini Apps importer.
  @remnic/import-mem0      mem0.ai REST importer.
  @remnic/import-supermemory  Supermemory JSON export importer.
  @remnic/import-weclone   WeClone-preprocessed chat export importer.
  @remnic/import-lossless-claw  lossless-claw (LCM) SQLite importer.
  @joshuaswarren/openclaw-engram  Deprecated compatibility shim; re-exports
                           @remnic/plugin-openclaw and forwards `engram-access`.

Also published:
  remnic-hermes            Python (PyPI) MemoryProvider plugin for Hermes
                           Agent. Talks to the daemon over HTTP.
Not published:
  @remnic/bench-ui         Private Vite dashboard for benchmark summaries.

Adapters never leak host-specific contracts back into `@remnic/core`. Core
owns memory behavior; each adapter maps that behavior onto its host's plugin
SDK, hooks, and manifest. Core never imports a host package.


THREE-PHASE FLOW

  1. Recall   Before an agent turn, inject relevant memories into context.
  2. Buffer   After a turn, accumulate content until a trigger fires.
  3. Extract  Periodically, distill structured memories via an LLM call.

Importance gating keeps trivial content off disk. Recall runs three
specialized retrievers in parallel (latency = max, not sum), with graceful
per-retriever degradation and zero extra LLM cost:
  DirectFact   Entity-filename keyword overlap (single-digit ms).
  Contextual   Hybrid BM25 + vector search.
  Temporal     Date index with recency-decay scoring.


STORAGE FORMAT

Plain markdown + YAML frontmatter, one file per memory. Categories include
fact, decision, preference, correction, relationship, principle, commitment,
moment, skill, rule, and entity. Lifecycle: active -> validated -> stale ->
archived. Episode/note model separates time-specific events from stable
beliefs. Inline provenance tags carry source attribution in the fact body.



OKF CONFORMANCE

Memory directories are OKF v0.1 knowledge bundles. Spec (pinned revision):
https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a/okf/SPEC.md
Every memory file carries an inert `type` field alongside the canonical
`category`; `type` never overrides `category` on parse. `remnic okf lint`
reports conformance findings (exit 1 when any remain; --json supported).
`remnic okf sweep` backfills missing `type` values without bumping
`updated` (opt-in via okf.sweepEnabled, default false; `type` emission
itself is gated by okf.conformanceEnabled, default true).
`remnic export okf --out <dir>` writes a portable plaintext OKF bundle
(lossy interchange). Capsules remain the lossless Remnic transport.
Full mapping and finding codes: docs/okf.md.

SEARCH BACKENDS

Six backends, selected by `searchBackend`:
  qmd          Default. Hybrid BM25 + vector + reranking via QMD.
  orama        Embedded JavaScript index.
  lancedb      Embedded native Arrow index.
  meilisearch  External Meilisearch server.
  remote       HTTP REST backend.
  noop         Extraction only, no search.

QMD target: @tobilu/qmd 2.5.3. Remnic probes `qmd --version` and gates newer
flags: 2.5.3+ uses `--format json` for query/search subprocess output; older
supported QMD installs keep legacy `--json`. Default query strategy is
`hybrid` and the default subprocess strategy is `query` (both BY DESIGN; do
not present BM25-only as the recommended default). Daemon timeout 8000 ms;
query-time rerank on.


KEY FEATURES

Core (on by default):
  - Automatic extraction and recall injection.
  - Entity tracking (basic relationship links).
  - Memory lifecycle policy (retention/tiering light-sleep phase).
  - Importance-gated extraction.
  - Inline source attribution.
  - Procedural memory mining (default-on; conservative preset pins it off).
  - Trust zones: quarantine -> working -> trusted provenance tiers with
    promotion rules and poisoning defense.

Opt-in (default off unless noted):
  - Lossless Context Management (LCM): proactive SQLite session archive +
    hierarchical summary DAG re-injected on compaction. On in research-max.
  - Extraction judge: LLM-as-judge durability filter, shadow mode available.
  - Semantic chunking: topic-boundary detection via sentence embeddings.
  - Semantic consolidation: cluster + synthesize canonical memories.
  - Page versioning: numbered snapshots per overwrite; list/diff/revert.
  - MECE taxonomy: deterministic categorization decision tree.
  - Enrichment pipeline: importance-tiered external entity enrichment.
  - Binary lifecycle: mirror/redirect/clean stages for binary files.
  - Namespaces: per-principal isolation with read/write ACLs.
  - Secure store: at-rest encryption (encrypt-on-write; unlock to read).
  - Wearables: Limitless / Bee / Omi transcript capture and fusion.
  - Graph recall / multi-graph memory + graph edge decay.
  - Recall direct-answer: observation-only tier annotation (never
    short-circuits QMD).
  - Dreams pipeline: lightSleep on; rem and deepSleep off by default.
  - Coding graph: code-symbol knowledge graph for coding agents.

Verify any default in packages/remnic-core/src/config.ts or the
openclaw.plugin.json configSchema before relying on it.


ACCESS LAYER

HTTP API (@remnic/server, or embedded in the OpenClaw host):
  Bearer-token auth (constant-time compare), binds to loopback by default.
  REST routes under /engram/v1/... (compatibility prefix): 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. Single MCP transport at
  POST /mcp. Exception route: POST /v1/citations/observed (no /engram prefix).

MCP tools:
  Over 100 tools, exposed over stdio and HTTP. Each canonical `remnic.*` name
  is paired with an `engram.*` legacy alias. Covers recall (with X-ray and
  tier-explain), store, memory search, entity lookup, LCM search, trust-zone
  inspection, observation, correction planning, peers, wearables, and
  maintenance. Every MCP tool ships an outputSchema.

Standalone CLI (`remnic`, 35 top-level commands, plus a
`benchmark` alias of `bench`):
  init, migrate, status, query, action-confidence, xray, doctor, config,
  daemon, token, tree, onboard, curate, review, sync, offline, oauth, dedup,
  connectors, space, bench (alias benchmark), briefing, versions, binary,
  taxonomy, enrich, procedural, openclaw, extensions, training:export, import,
  import-lossless-claw, wearables, capsule.
  Full reference: docs/cli.md.

OpenClaw-hosted surface (`openclaw engram <command>`):
  Roughly 100 subcommands registered by core inside the OpenClaw host for
  operators (tier, forget/purge, namespaces, capsule, secure-store, peer,
  dreams, governance, benchmark, and more). There is no `openclaw remnic`
  shell namespace; the in-chat session command is `/remnic <on|off|status|
  clear|stats|flush>`. See docs/api.md.

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


CONFIGURATION

Standalone resolution order: `--config` > REMNIC_CONFIG_PATH (legacy
ENGRAM_CONFIG_PATH) > ./remnic.config.json > ./engram.config.json >
~/.config/remnic/config.json > ~/.config/engram/config.json. The standalone
file has a top-level `remnic` block plus a separate `server` block
(host/port/authToken/principal). Under OpenClaw, config lives at
plugins.entries.openclaw-remnic.config (legacy openclaw-engram fallback),
schema-validated with additionalProperties:false.

Hundreds of options across the schema, four presets (`memoryOsPreset`):
  conservative     Minimal footprint; pins procedural memory off.
  balanced         Query-aware indexing, verbatim artifacts, local rerank.
  research-max     Graph recall, proactive extraction, compression, LCM on.
  local-llm-heavy  Local LLM + fast local path, local embedding fallback.
(`research` is an alias for `research-max`.) User keys win over the preset;
the `procedural` block is deep-merged so a partial override cannot discard a
preset's pinned value.

LLM routing: OpenAI API, local LLM (Ollama, LM Studio), or a gateway model
chain with multi-provider fallback. For the exact option count run
`npm run check-config-contract`; full reference in docs/config-reference.md.


QUICK START (STANDALONE)

  npm install -g @remnic/cli
  remnic init
  export OPENAI_API_KEY=<your-key>
  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

Use the explicit `clawhub:` source for deterministic installs;
`npm:@remnic/plugin-openclaw@<version>` for npm-only fallback or rollback.


CONNECTING OTHER AGENTS

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

Hermes discovers memory providers by scanning $HERMES_HOME/plugins/<name>/,
not pip metadata: the pip package must be bridged by a shim
(~/.hermes/plugins/remnic/__init__.py re-exporting remnic_hermes.register)
and selected via memory.provider in Hermes config.yaml. Memory is injected
through the provider's synchronous prefetch() (bounded by the
prefetch_wait_timeout config, default 2.0s); Hermes never calls
pre_llm_call on memory providers. The daemon's /recall returns profile and
knowledge-index context even when count == 0; the plugin injects it either
way. See docs/plugins/hermes.md.

Built-in connector ids: claude-code, codex-cli, cursor, cline,
github-copilot, roo-code, windsurf, amp, pi, omp, replit, generic-mcp,
weclone, hermes.


CHATGPT DEVELOPER MODE

ChatGPT can persist memory across conversations using your own infrastructure
as the source of truth. OpenAI no longer disables built-in memory when you
connect a custom MCP server, so Remnic plugs in as an MCP + OAuth 2.1
integration. The canonical store stays on your disk; when ChatGPT calls
Remnic's tools, those tool inputs/outputs are processed by OpenAI. The OAuth
authorization server is the facade in @remnic/server; the connector id is
`chatgpt` (token prefix remnic_cg_). Reach it via Tailscale Funnel or
Cloudflare Tunnel with local operator approval (`remnic oauth
pending|approve|deny`). Setup guide: docs/integration/chatgpt.md.


OPENCLAW PLUGIN COMPATIBILITY

Policy: Remnic supports OpenClaw releases from at least the previous 60 days.
Recalculate the floor from the current date before changing package metadata;
only raise it when an upstream breaking change makes an older host impossible
to support.

The August 14, 2026 Support Passport sweep starts at June 15, 2026. The
existing `>=2026.4.1` installer floor remains more permissive and stays in
place.

Host-upgrade pairing: OpenClaw 2026.8.1 (2.0) removed the
`registerMemoryPromptSection` SDK API. Plugin versions up to and including
9.69.56 load on 2.0 and run the daemon loop, but bridge/delegate mode injects
no memory into agent prompts. Upgrading the host to 2.0 requires
@remnic/plugin-openclaw >= 9.69.57. OpenClaw 1.x hosts (2026.4 through
2026.7.x) and embedded (non-delegate) memory mode are unaffected on every
plugin version (issue #3057).

`openclaw.compat.pluginApi` and `openclaw.install.minHostVersion` use one
`>=2026.4.1` comparator, never a `||` list: OpenClaw's installer splits the
range on whitespace and AND-evaluates every token (a `||` fails entirely) and
normalizes away the host prerelease suffix, so a single floor admits both
stable and prerelease hosts (issue #1450). Reviewed prereleases are listed
ONLY in `peerDependencies.openclaw` (a `||` list), because npm/node-semver
resolves that field and drops prereleases from a bare `>=` range.

Manifest stays on current native fields: kind="memory", contracts.tools
(every Remnic-owned tool name, including conditional LCM aliases),
commandAliases, activation, setup.requiresRuntime=false, and
setup.providers[].envVars for optional OPENAI_API_KEY. Keep providerAuthChoices
and mirror providerAuthEnvVars/supports for older hosts. Do not add top-level
securityDisclosure. Source of truth:
packages/plugin-openclaw/openclaw.plugin.json. Compatibility sweeps and
ClawHub publish mechanics live in docs/plugins/openclaw.md.


LEGACY ENGRAM MIGRATION

For @joshuaswarren/openclaw-engram 9.2.x -> @remnic/plugin-openclaw:

  remnic openclaw migrate-engram --yes

Canonical OpenClaw plugin id is openclaw-remnic; the legacy id is
openclaw-engram. `remnic-workspace` is the npm workspace root, never an
OpenClaw plugin id. The migration backs up openclaw.json and the legacy
extension dir, installs the new plugin, rewrites plugins.entries and
plugins.slots.memory, and preserves memoryDir. Guide:
docs/guides/openclaw-engram-to-remnic.md.


DOCUMENTATION

  README.md                     Overview, install, feature list, architecture.
  docs/README.md                Docs hub, organized by journey.
  docs/guides/quickstart.md     Five-minute universal path.
  docs/getting-started.md       Comprehensive install and first-run guide.
  docs/cli.md                   Full standalone `remnic` CLI reference.
  docs/config-reference.md      Every configuration option.
  docs/api.md                   HTTP, MCP, and `openclaw engram` reference.
  docs/search-backends.md       Backend comparison + QMD version gating.
  docs/namespaces.md            Namespace isolation and principals.
  docs/import-export.md         Data portability.
  docs/operations.md            Day-two operations.
  docs/architecture/            Per-subsystem architecture docs.
  docs/plugins/openclaw.md      OpenClaw adapter, compat policy, publishing.
  docs/integration/             Per-host connector setup guides.
  docs/security/                Threat models and security notes.
  SECURITY.md                   Vulnerability reporting and disclosure.
  AGENTS.md / CLAUDE.md         Agent operating rules and privacy policy.


BUILD / TEST / DEVELOP

  Install:      pnpm install
  Build:        pnpm run build
  Test:         pnpm test
  Typecheck:    pnpm run check-types
  Quality gate: pnpm run preflight:quick
  Config check: npm run check-config-contract
  Docs parity:  npm run check:docs-parity
  Eval suite:   npm run bench:run

Contributor guide: docs/development/contributing.md.