# Remnic

> Persistent, private, local-first memory for AI agents. Works with Claude Code,
> Codex CLI, Cursor, Hermes Agent, OpenClaw, Replit, and any MCP-compatible client.
> Open source, MIT licensed, free forever.

Remnic is a universal memory layer for AI agents. It watches your agent
conversations, extracts durable knowledge, and injects the right memories back
into the prompt at the right time. All data stays on your machine as plain
markdown files with YAML frontmatter. No cloud services, no telemetry, no
subscriptions, no vendor lock-in.

One memory store is shared across every supported agent — tell Claude Code a
preference and your Codex CLI, Cursor, Hermes Agent, and OpenClaw all know it
too.

## Key facts

- License: MIT
- Source: https://github.com/joshuaswarren/remnic
- CLI install: `npm install -g @remnic/cli`
- Daemon install: `remnic daemon install`
- Config home: `~/.remnic/`
- Server port: 4318 (loopback by default)
- Node.js required: 22.12+
- Author: Joshua Warren <https://github.com/joshuaswarren>
- Sponsor: https://github.com/sponsors/joshuaswarren

## Core docs

- [Homepage](https://remnic.ai/): overview and install
- [Install guide](https://remnic.ai/install): 60-second setup
- [Features](https://remnic.ai/features): 60+ capabilities
- [Memory quality design notes](https://remnic.ai/memory-quality): how Remnic controls signal-to-noise
- [Compare vs alternatives](https://remnic.ai/compare): Remnic vs mem0, Letta, Supermemory, ChatGPT memory
- [Engram → Remnic rename](https://remnic.ai/rename): migration notes

## Integrations

- [Claude Code](https://remnic.ai/claude-code): native plugin with hooks, skills, MCP
- [Codex CLI](https://remnic.ai/codex-cli): native plugin with hooks, MCP, phase-2 extension
- [Hermes Agent](https://remnic.ai/hermes): Python MemoryProvider for structural recall
- [OpenClaw](https://remnic.ai/openclaw): native memory slot plugin
- [Cursor & MCP](https://remnic.ai/cursor): any MCP-compatible client (Cline, Windsurf, Amp, Replit, custom)

## Packages

- `@remnic/core` (v1.0.2) — framework-agnostic engine
- `@remnic/cli` (v1.0.4) — CLI binary with 20+ commands
- `@remnic/server` (v1.0.4) — standalone HTTP + MCP server
- `@remnic/plugin-openclaw` (v1.0.5) — OpenClaw adapter
- `@remnic/plugin-claude-code` (v1.0.0) — Claude Code plugin
- `@remnic/plugin-codex` (v1.0.0) — Codex CLI plugin
- `@remnic/hermes-provider` (v1.0.0) — TypeScript HTTP client
- `remnic-hermes` (v1.0.1, PyPI) — Python MemoryProvider for Hermes Agent

## Three-phase memory loop

1. Recall — before each agent turn, Remnic injects relevant memories using
   hybrid BM25 + vector search with reranking.
2. Buffer — after each turn, conversation content is buffered. Smart signals
   decide when enough context has accumulated.
3. Extract — durable facts, preferences, decisions, and patterns are extracted
   via LLM (OpenAI, local LLM, or gateway model chain) and stored as markdown.

## Major features

- Local-first storage: plain markdown with YAML frontmatter
- Hybrid search: BM25 + vector + reranking via QMD; six pluggable backends
- Entity graph: people, projects, tools, relationships as structured entities
- Memory lifecycle: active → validated → stale → archived
- Importance-gated writes: trivial content never hits disk
- Lossless Context Management (LCM): proactive session archive + hierarchical summary DAG
- Parallel specialized retrieval: DirectFact + Contextual + Temporal agents
- Semantic consolidation: clusters of similar memories merged via LLM
- Trust zones: quarantine → working → trusted with promotion rules
- MECE taxonomy: deterministic memory categorization
- Page versioning: snapshot-based history with diff and revert
- Governance: review queues, shadow/apply modes, reversible transitions
- Namespaces: multi-agent memory isolation
- LLM routing: OpenAI, Ollama, LM Studio, vLLM, or gateway model chain
- 90+ config properties with presets (conservative, balanced, research-max, local-llm-heavy)
- 672+ tests with CI enforcement

## HTTP API

Bearer-token auth, loopback by default. Paths currently under `/engram/v1/*`
during the v1.x compatibility window.

- `GET /engram/v1/health`
- `POST /engram/v1/recall`
- `POST /engram/v1/memories` (CRUD)
- `GET /engram/v1/entities/:name`
- `POST /engram/v1/observe`
- `POST /engram/v1/lcm/search`
- `GET /engram/v1/trust-zones/status`
- `POST /engram/v1/trust-zones/promote`
- Operator UI: `http://127.0.0.1:4318/engram/ui/`

## MCP tools (14+)

- `engram.recall` — retrieve relevant memories for a query
- `engram.recall_explain` — debug the last recall
- `engram.memory_get` — fetch a specific memory by ID
- `engram.memory_store` — store a new memory
- `engram.memory_timeline` — view a memory's lifecycle
- `engram.entity_get` — look up a known entity
- `engram.day_summary` — structured end-of-day summary
- `engram.observe` — feed conversation into pipeline
- `engram.lcm_search` — full-text search archived conversations
- `engram_context_expand` — retrieve raw lossless messages
- `engram.review_queue_list` — governance review queue
- `engram.suggestion_submit` — queue a memory for review

## Quick start (standalone)

```
npm install -g @remnic/cli
remnic daemon install
remnic connectors install claude-code
remnic connectors install codex-cli
remnic connectors install hermes
remnic connectors doctor
```

## Optional: Cookies, telemetry

Remnic has no cookies, no telemetry, no analytics. The website remnic.ai uses
Google Fonts (Inter, JetBrains Mono) via CDN. That is the only third-party
resource loaded.