User model, not just storage
Track preferences, goals, projects, constraints, priorities, communication style, risk tolerance, relationships, past decisions, and definitions of good.
Open-source project · MIT licensed · local-first trust
Open-source memory and context
Open-source memory and context
for user-aware agents.
Remnic helps AI agents understand the people they work with: their preferences, projects, constraints, decisions, patterns, and definition of good. The goal is simple: agents that remember responsibly, retrieve the right context, and ask fewer unnecessary questions.
$
npm install -g @remnic/cli && remnic daemon install The problem
Agents need more than stored facts.
A useful agent needs a working model of the user in front of it: preferences, goals, projects, constraints, current priorities, communication style, risk tolerance, relationships, past decisions, and boundaries around what memory can be used where.
The core question is not "what can the agent remember?" It is: what does the agent need to understand about this user to act well right now, and when should it ask before acting?
Without Remnic
- Facts get stored without clear scope
- Agents miss preferences and definitions of good
- Stale context can be retrieved as if it is current
- Corrections are hard to trace or apply
- The agent asks low-value questions or acts too soon
With Remnic
- User context is modeled, scoped, and inspectable
- Retrieved memory carries source, confidence, and reason
- Corrections and staleness influence recall
- Boundaries prevent context from leaking across scopes
- Action confidence helps agents spend attention carefully
User-aware agents
Personalization with boundaries.
Remnic is not just a memory store. It is an exploration of the systems layer around user-aware agents: scoped memory, provenance, retrieval quality, correction, boundaries, and evals.
Provenance on every recall
Know where memory came from, when it was created, what scope it belongs to, why it was retrieved, and whether it is stale or corrected.
Scopes and boundaries
Personal, work, client, project, repo, tool, temporary, private, and do-not-use-outside-this-context scopes keep personalization from becoming surveillance.
Ask-versus-act decisions
Action confidence helps an agent decide whether to ask, draft, act, refuse, or escalate. A good agent should spend the user's attention carefully.
Memory or user context?
Both. Without compromise.
Remnic combines a memory engine with a durable user-context layer. Files remain the source of truth, retrieval stays sharp, and the system keeps enough metadata to decide whether memory is relevant, safe, stale, or worth asking about.
Files are the source of truth
- Every memory is markdown + YAML on your disk
cat,grep, edit, git, back up — standard tools- QMD search index is downstream and fully rebuildable
- Page versions snapshot every overwrite — diff and revert any time
The recall stays sharp
- Hybrid search: BM25 + vector + reranking via QMD
- Feature-flagged graph retrieval with Personalized PageRank
- Memory-worth scoring filters low-value facts before the LLM sees them
- Recall X-ray shows exactly which tier produced each result, and why
- Project-scoped memory keeps codebases isolated — core patterns and framework knowledge stay global
Context compounds over time
- Background consolidation merges duplicates and promotes recurring themes
- Provenance fields track where every consolidated fact came from
- Default-on procedural memory captures multi-step runbooks
- Temporal supersession keeps stale facts out of recall automatically
One memory layer for every agent
Works with the tools you already use.
Native integrations for Claude Code, Codex CLI, Pi Coding Agent, Hermes, and OpenClaw. MCP for everything else. Give your WeClone avatar memory. Share one store across every client.
CC
Claude Code
Hooks + MCP + slash commands. 44 tools.
CX
Codex CLI
Hooks, MCP, and a memory extension for phase-2 consolidation.
PI
Pi Coding Agent New
Native extension with turn recall, observation, MCP tools, and LCM compaction coordination.
HM
Hermes Agent
Python MemoryProvider — structural recall, no tool call needed.
OC
OpenClaw
Native memory slot plugin. The flagship integration.
WC
WeClone New
Memory-aware proxy, chat-history import, and training-data export for your AI avatar.
CS
Cursor
MCP over HTTP. On-demand recall and store.
+
Cline · Windsurf · Amp · Replit
Any MCP-compatible client picks up Remnic automatically.
API
HTTP + REST
Authenticated REST API for custom agent integrations.
How it works
Three-phase memory loop, every turn.
Remnic sits alongside your agents and manages memory across three phases that run continuously. Nothing is optional — recall is structural.
1
Recall
Before each agent turn, Remnic injects relevant memories using hybrid BM25 + vector search with reranking. Your agent starts every turn already informed — no tool call required.
2
Buffer
After each turn, conversation content is buffered. Smart signals decide when enough context has accumulated to extract durable knowledge.
3
Extract
Durable facts, preferences, decisions, and patterns are extracted and stored as markdown files. Use OpenAI, a local LLM, or a multi-provider fallback chain.
Your data, your disk
Plain markdown. Nothing hidden.
Every memory is a human-readable markdown file with YAML frontmatter. You can
grep it, diff it, edit it, delete it, version-control it. No opaque
database stands between you and your own context.
- Stored at
~/.remnic/memory/ - 11+ memory categories: fact, decision, preference, correction, principle, commitment…
- Back up with git, rsync, or Time Machine
- Move machines with a folder copy
- No cloud, no subscription, no lock-in
~/.remnic/memory/decisions/search-backend.md ---
id: decision-1738789200000-a1b2
category: decision
confidence: 0.92
created: 2026-03-15T09:14:22Z
tags: ["architecture", "search"]
entities: [remnic, qmd, pgvector]
---
Decided to use the port/adapter pattern for
search backends so QMD, Orama, LanceDB, and
Meilisearch can all plug in without changing
core logic.
Rationale: lets us swap engines per deployment
without forking the memory pipeline.
Under the hood
Infrastructure for agents that know when to ask.
Remnic builds toward the infrastructure agents need to understand users over time: memory, context, retrieval, correction, boundaries, evals, and action-confidence signals.
Retrieval quality
BM25 + vector search + reranking via QMD. Six pluggable backends plus recall budgets keep retrieved context relevant and bounded.
User model
Preferences, constraints, projects, goals, relationships, communication style, risk tolerance, decisions, and definitions of good can become first-class context.
Scoped memory
Personal, work, client, project, repo, tool, temporary, private, and do-not-use-outside boundaries keep memory useful without leaking context.
Correction loop
User corrections and stale-memory signals are tracked as part of memory state, so later recall can prefer corrected and current context.
Provenance and trust
Source, timestamp, scope, confidence, retrieval reason, and trust-zone state help agents explain why a memory surfaced and whether to use it.
Recall observability
Know exactly why each memory surfaced. recall/explain, tier-explain, and recall audit trail answer which tier served this result and why.
Action confidence
Remnic can help an agent decide whether to ask, draft, act, refuse, or escalate when memory is incomplete, stale, private, or out of scope.
Entity graph
People, projects, tools, and companies are tracked as structured entities with relationships that help recall preserve real working context.
Memory inspection
Plain markdown files, version snapshots, HTTP endpoints, and operator surfaces make it possible to inspect, correct, forget, and rescope memory.
MCP and Apps path
A standalone MCP server gives ChatGPT Apps-style clients and developer tools a standard way to inspect, recall, store, correct, and scope memory.
Memory evals
Benchmark packs, shadow recall recording, and CI delta gates evaluate whether memory reduced repeated context, respected scope, and improved output.
Bring your own model
OpenAI, Ollama, LM Studio, or a gateway chain.
Run Remnic extraction and reranking on OpenAI, a local model via
Ollama or LM Studio, or route through a gateway model chain with
multi-provider fallback — Fireworks → local LLM → cloud OpenAI, for
example. The local-llm-heavy preset is optimized for
fully offline operation.
OpenAI Ollama LM Studio vLLM Fireworks Groq Anthropic Any OpenAI-compatible
Install what you need
Modular packages, independently versioned.
Every package is published under the @remnic scope on npm and
installed on demand. TypeScript ESM monorepo with pnpm workspaces.
@remnic/core v1.1.12
Framework-agnostic engine. Orchestrator, storage, search, extraction, graph, trust zones, LCM.
@remnic/cli v1.0.8
CLI binary — init, query, doctor, daemon management, 20+ commands.
@remnic/server v1.0.5
Standalone HTTP + MCP server. Multi-token auth, daemon via launchd/systemd.
@remnic/plugin-openclaw v1.0.35
OpenClaw adapter. Embedded or delegate mode, native memory slot.
@remnic/plugin-claude-code v1.0.1
Claude Code plugin — hooks, skills, and MCP integration.
@remnic/plugin-codex v1.0.1
Codex CLI plugin — hooks, MCP, and memory extension for phase-2 consolidation.
@remnic/plugin-pi v1.0.0
Pi Coding Agent extension — context hook recall, turn observation, MCP tools, and LCM compaction coordination.
@remnic/hermes-provider v1.0.2
Typed HTTP client for the Remnic memory API. Use it from any TypeScript app.
remnic-hermes v1.0.2 · PyPI
Python MemoryProvider plugin for Hermes Agent. Structural recall, daemon-side LCM, and full tool parity.
@remnic/connector-weclone v1.0.1
OpenAI-compatible proxy adding persistent memory to deployed WeClone avatars.
@remnic/import-weclone v1.0.1
Bulk-import WeClone-preprocessed chat exports (Telegram, WhatsApp, Discord, Slack) to seed your memory store.
@remnic/export-weclone v1.0.1
Export Remnic memories as Alpaca-format fine-tuning datasets for LLaMA Factory + WeClone.
@remnic/import-chatgpt v0.1.0
Import saved ChatGPT memories and optional conversation summaries from OpenAI data exports.
@remnic/import-claude v0.1.0
Import Claude project docs and prompt templates as provenance-tagged Remnic memories.
@remnic/import-gemini v0.1.0
Import Google Takeout Gemini Apps Activity into your local memory store.
@remnic/import-mem0 v0.1.0
Import mem0 memories through the REST API with pagination and rate-limit controls.
@remnic/import-supermemory v0.1.2
Import Supermemory JSON exports with provenance metadata and dry-run previews.
Frequently asked
Common questions.
What makes Remnic different from mem0, Letta, Zep, Supermemory, or MemPalace?
Remnic sits in a quadrant no one else occupies: local-first, free, and multi-host. mem0, Letta, Zep, and Supermemory are cloud-biased (Zep also needs a graph database you run). MemPalace is local and free but single-host. Remnic runs on your machine as plain markdown files, is MIT licensed, ships native plugins for Claude Code, Codex CLI, Pi Coding Agent, Hermes, OpenClaw, Cursor, and any MCP client, and exposes full recall observability so you can see exactly why each memory surfaced. See the full comparison.
Can I see why Remnic surfaced a memory?
Yes. Every recall can be queried with recall/explain,
which returns the tier that served each result, the score
decomposition, the graph path (when graph retrieval fired), and the
audit trail ID. Most competitors treat retrieval as a black box;
Remnic does not.
Does Remnic handle contradictory memories over time?
Yes. Remnic applies write-time supersession on structured attributes
(a new fact with a matching supersession key marks the prior as
superseded) and runs an overnight contradiction-scan
cron that pairs semantically-similar active memories, classifies
them with an LLM-as-judge, and queues contradicting pairs for user
resolution. No auto-delete — the human always approves.
Does Remnic remember "how" to do things as well as facts?
Yes. Procedural memory is enabled by default and lets you
teach Remnic a multi-step runbook ("deploy the gateway", "open a
regression PR", "rotate credentials"), it saves the procedure as a
category: procedure memory and injects a Relevant
procedures block the next time the agent looks like it's
starting the same task. A trajectory miner also clusters
repeat-after-repeat behavior into pending-review procedure
candidates you approve. Set procedural.enabled: false in
config if you want to opt out. See
docs/procedural-memory.md.
Does Remnic work offline?
Yes. Remnic can run extraction and reranking on a local LLM via Ollama,
LM Studio, vLLM, or any OpenAI-compatible endpoint. The
local-llm-heavy preset is tuned for fully offline operation.
Do I need OpenClaw?
No. Remnic works standalone with @remnic/cli and
@remnic/server. OpenClaw is one of several first-class
integrations, not a requirement.
How do I install it?
npm install -g @remnic/cli && remnic daemon install. Then
run remnic connectors install claude-code (or
codex-cli, pi, hermes,
openclaw, or replit) to wire
up the agent you use. Full walkthrough on the install page.
Is Remnic really free?
Yes. MIT licensed, no subscriptions, no telemetry. If Remnic saves you real time, sponsor the project on GitHub or star the repo to help others find it.
Give your agents context they can use responsibly.
Two commands. One minute. Every AI tool you use can share scoped, inspectable memory with provenance, correction, and boundaries.