Mnemic

Mnemic is a local-first memory kernel for coding agents and LLM applications.

It gives Codex, Claude Code, Cursor, Copilot-style agents, and custom MCP clients one shared, auditable, graph-backed long-term memory layer. Agents write source-keyed memories, preview changes before they become durable, recall facts as of a point in time, explain why recall selected a record, and turn the memory graph into prompt-ready context packs and session briefings.

The repo is TypeScript-first, MCP-native, and shaped for the 2026 agent-memory stack: durable memory outside the context window, inspectable provenance, local defaults, governance before writes, and reproducible evals.

Why Mnemic

Mnemic is not a vector-store wrapper or a hidden chat-summary cache. It is a repo-scoped memory plane that agents can inspect, replay, and govern.

Modern agent platforms already treat memory as infrastructure: MCP standardizes tool and data connections, agent SDKs expose session state, and long-term memory benchmarks increasingly test temporal recall, workflow knowledge, and stale facts. Mnemic focuses on the missing developer layer between those pieces.

Related MCP server: Archivist MCP

Five-Minute Demo

npm install
npm run demo

The demo starts an isolated backend on a random local port, writes a small coding-agent memory graph, previews an idempotent update, explains recall, builds a context pack, prints a session briefing, audits memory hygiene, shows the append-only timeline, replays an event-log snapshot, and writes a launch report.

The same replay path is available from the CLI as mnemic snapshot, from MCP as mnemic_snapshot, and from HTTP as GET /api/agent-memory/snapshot.

Expected landmarks:

Mnemic Memory Write Preview
sourceKeyMatched: true
changedFields: confidence, content, importance, updatedAt

Mnemic Recall Explanation
matchedFields: content, sourceKey, tags, title
relationPaths: ...

Mnemic Memory Audit
blocks: 0
warnings: 0

Mnemic Memory Snapshot
eventsReplayed: 5
relations: 2

Demo artifacts are written to target/mnemic-launch-demo/, including mnemic-launch-report.md. Demo details live in examples/coding-agent-memory.

Quickstart

Initialize local config for a clone:

npm run init

This generates .env.mnemic, .mnemic/policy.json, .mcp.json, and AGENTS.mnemic.md without overwriting existing files. Use node mnemic-cli/dist/index.js init --force to refresh generated files.

Run the readiness doctor:

npm run doctor

Validate the OpenAPI contract:

npm run openapi:check

Run the deterministic benchmark:

npm run benchmark

It writes target/mnemic-benchmark/mnemic-eval-report.md and currently checks recall@5, mean hit rank, stale false positives, relation-path coverage, and latency without requiring a model provider. See docs/benchmark-baseline.md and docs/benchmark-landscape.md.

Docker

docker compose -f docker-compose.agent-memory.yml up -d --build mnemic-memory-backend
curl -fsS http://127.0.0.1:8088/actuator/health

See docs/docker-quickstart.md for SQLite mode, stop commands, optional Neo4j profile, and Docker readiness checks.

What Ships Today

Launch Gates

npm run launch:check
npm run docs:check
npm run rewrite:check
npm run completion:check
npm run fresh:check
npm run github:launch:check
npm run docker:check
npm run repository:check
npm run public:check
npm run supply:check
npm run community:check
npm run security:check
npm run benchmark:landscape:check
npm run market:check
npm run release:notes
npm run release:check
npm run package:check
npm run ci:smoke

npm run completion:check verifies the completion audit that maps the original rename, TypeScript rewrite, and 2026 agent-memory direction to current source evidence and remaining release blockers.

npm run repository:check verifies package metadata and launch docs point at the final Mnemic repository target and that non-Mnemic repository identities do not leak into the public tree.

npm run public:check summarizes public-launch state: target origin, clean worktree, remote repository reachability, GitHub About metadata, hosted CI/CodeQL proof, and npm publication blockers. Use strict mode after the repository is renamed and pushed.

npm run supply:check verifies lockfile shape, npm audit at the high threshold, package-manager pinning, npm token boundaries, trusted-publishing docs, and private package status.

npm run community:check verifies GitHub community-health files such as support policy, code of conduct, Dependabot config, and release checklist coverage.

npm run security:check verifies CodeQL workflow configuration, security docs, Dependabot coverage, and security hardening release gates.

npm run launch:check verifies the GitHub-facing path: README visual card, Studio preview image, demo, benchmark/readiness commands, temporal snapshot messaging, release checklist coverage, Docker link, and package discovery keywords.

npm run docs:check verifies README Docs Map coverage and local Markdown links/images across the public documentation surface.

Refresh the Studio preview asset after meaningful UI changes:

npm run studio:capture

Connect An Agent

Run a local backend:

cp .env.mnemic.example .env.mnemic
scripts/start-agent-memory-stack.sh

Install the Codex MCP entry:

scripts/install-codex-mcp.sh

Generic MCP client snippets are in docs/mcp-client-configs.md. Detailed API, CLI, MCP, governance, SDK, and storage usage lives in docs/usage.md.

Docs Map

• docs/usage.md: API, CLI, MCP tools, SDK examples, governance, storage.

• docs/agent-memory-architecture.md: runtime shape and memory model.

• docs/mnemic-2026-roadmap.md: product thesis and roadmap.

• docs/benchmark-landscape.md: public benchmark positioning and adapter plan.

• docs/local-readiness.md: doctor checks and local troubleshooting.

• docs/docker-quickstart.md: fresh-clone Docker setup.

• docs/github-actions.md: CI, eval, policy, and PR memory-review workflows.

• docs/github-launch.md: GitHub About text, topics, launch copy, and benchmark claim guardrails.

• docs/security-hardening.md: CodeQL, Dependabot, sensitive-data, and security-release boundaries.

• docs/supply-chain.md: lockfile, audit, package provenance, and npm trusted-publishing boundaries.

• docs/repository-migration.md: GitHub repository identity and package metadata target.

• docs/completion-audit.md: original-goal completion evidence and remaining release blockers.

• docs/release-checklist.md: release and package-readiness checks.

• docs/npm-publishing.md: guarded npm publishing strategy.

• docs/releases/v0.1.0.md: current launch-candidate release notes.

• docs/openapi.json: machine-readable HTTP API contract.

Workspace

• mnemic-sdk/ contains the shared TypeScript contracts and HTTP client.

• mnemic-cli/ contains the command-line workflow entrypoint.

• mnemic-server/ is the TypeScript backend.

• mcp-server/ exposes Mnemic memory through MCP tools.

• studio/ is the React workbench. The active product path is the TypeScript workspace.

Open Source

• License: MIT

• Contributions: CONTRIBUTING.md

• Code of conduct: CODE_OF_CONDUCT.md

• Security: SECURITY.md

• Support: SUPPORT.md

• Changelog: CHANGELOG.md