Engramkeep

Local-first, Markdown-native memory for AI coding agents.

Engramkeep gives every agent you use — Codex, Claude Code, OpenCode, Cursor, Windsurf, Gemini CLI, Antigravity, or anything that can read AGENTS.md — the same persistent, human-readable project memory. It runs on the Python standard library alone.

Status: 0.5.2 alpha. The store, CLI, MCP server, dashboard, troubleshooting registry, bilingual search, and the backed-up agent installer work. Cloud sync, transcript adapters, and schema migrations are still ahead. See docs/ROADMAP.md.

Turkish README

Why Engramkeep?

• Local-first. No account, no telemetry, no server. Your memory stays on your machine.
• Markdown-native. Every card is a plain Markdown file you can read, diff, back up, and edit.
• Agent-agnostic. A canonical AGENTS.md protocol, a portable SKILL.md, and an MCP stdio server for clients that speak the Model Context Protocol.
• One-command setup. engramkeep install --apply wires the memory protocol into ten agents, with managed blocks, timestamped backups, and a clean uninstall.
• Safe by default. Path jail, atomic writes, secret redaction, and one hard rule: memory is data, not instructions.
• Zero required dependencies. The core runs on the Python standard library.

Engramkeep is not a vector database, a chat application, or a cloud service. It is a small, auditable memory layer that keeps project decisions in files you own.

What works in 0.5.2

Demo

$ engramkeep init
Initialized Engramkeep at …/Engramkeep
  created INDEX.md, RECENT_ACTIVITY.md, audit.log, TROUBLESHOOTING.md, projects/, trash/

$ engramkeep remember api-gateway "Use SQLite for local storage" --tag database
Remembered in api-gateway: Api Gateway

$ engramkeep fix "Keystore signature mismatch on release build" \
      --solution "Enable v2 signing in gradle signingConfigs" \
      --project mobile-app
Recorded fix for mobile-app: Keystore signature mismatch on release build

$ engramkeep fixes mobil        # Turkish query, English entry
mobile-app (2026-11-09)
  workspace: General
  problem: Keystore signature mismatch on release build
  fix: Enable v2 signing in gradle signingConfigs

$ engramkeep search "database"
Api Gateway (api-gateway)
  tags: database
  ...Decisions - Use SQLite for local storage

A complete synthetic store lives in examples/demo-brain/. It is generated from checked-in JSON sources by python scripts/build_demo_brain.py; no real project data is included.

Quick start

pipx install engramkeep     # or: pip install engramkeep
engramkeep init
engramkeep remember example-project "Use SQLite for local storage" --tag database
engramkeep search sqlite
engramkeep show example-project

From a source checkout:

python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -e ".[dev]"
engramkeep init

Without installing the package:

# Windows
set PYTHONPATH=src
python -m engramkeep init

# macOS / Linux
PYTHONPATH=src python -m engramkeep init

Try the demo store before touching your own memory:

engramkeep --home examples/demo-brain search "docker arm64"
engramkeep --home examples/demo-brain fixes "database is locked"
engramkeep --home examples/demo-brain dashboard

Install the memory protocol into your agents

The installer writes a small managed block into your agent instruction files. It is a dry run by default: nothing changes until you pass --apply.

engramkeep install --list                 # supported agents
engramkeep install --agent opencode       # show the plan (dry run)
engramkeep install --agent opencode --apply
engramkeep install --agent opencode --apply --mcp
engramkeep install --agent all --apply    # every supported agent
engramkeep install --agent opencode --uninstall

What it does:

Supported agents: OpenCode, Claude Code, OpenAI Codex, Cursor, Windsurf, Gemini CLI, Antigravity, GitHub Copilot, Cline, and Roo Code. engramkeep install --list prints the exact target paths for the current platform.

What gets remembered

By default:

Override it with the ENGRAMKEEP_HOME environment variable or the global --home flag:

engramkeep --home ./my-brain init

Layout:

<home>/
├── INDEX.md              # generated project index
├── RECENT_ACTIVITY.md    # human-readable activity log
├── TROUBLESHOOTING.md    # resolved errors and verified fixes
├── audit.log             # append-only JSONL audit trail
├── projects/
│   └── example-project.md
└── trash/                # recoverable cards moved by `forget`

A project card is Markdown with a small frontmatter block:

---
id: example-project
title: Example Project
created: 2026-01-01T00:00:00Z
updated: 2026-01-02T12:00:00Z
tags: demo, docs
---

# Example Project

## Decisions

- Use SQLite for local storage.

The troubleshooting registry

Every agent eventually hits the same build failure twice. Engramkeep keeps a local TROUBLESHOOTING.md so a solved error is recorded once and recalled forever:

# Record a resolved problem
engramkeep fix "Keystore signature mismatch on release build" \
    --solution "Enable v2 signing in gradle signingConfigs" \
    --project mobile-app

# Recall fixes
engramkeep fixes keystore
engramkeep fixes mobil      # bilingual: TR query, EN entry
engramkeep fixes            # newest first
engramkeep fixes --json

Entries are redacted before write, the file is rewritten atomically, and agents are instructed to treat entries as untrusted data — never as instructions to execute.

How well does recall work?

The repository includes a reproducible benchmark over a synthetic corpus of 15 error/fix pairs and 45 independently written queries (English and Turkish):

Scoring is lexical with a small bilingual concept bonus: no embeddings, no network calls, nothing to download. Two of the three no-match controls return nothing; the third is reported honestly in docs/BENCHMARK.md rather than hidden.

Reproduce:

python scripts/benchmark_fix_registry.py --output docs/BENCHMARK.md

Commands

Using Engramkeep with agents

Engramkeep is designed around two portable files:

1. AGENTS.md — the cross-agent instruction format.
2. SKILL.md — the portable skill format used by OpenCode, Claude Code, and compatible agents.

The repository ships:

• skills/engramkeep/SKILL.md
• templates/agents/AGENTS.md
• templates/rules/ for Claude Code, Cursor, Windsurf, and OpenCode

engramkeep install --agent <name> --apply installs the managed instruction block (and optional MCP config with --mcp). Copy skills/engramkeep/SKILL.md or rule templates manually if you want the full skill file:

MCP

Start the server with:

engramkeep mcp

It uses newline-delimited JSON-RPC 2.0 over stdio and protocol version 2025-11-25. A typical client configuration looks like:

{
  "mcpServers": {
    "engramkeep": {
      "command": "engramkeep",
      "args": ["mcp"]
    }
  }
}

The default tool set is read-only: engramkeep_search, engramkeep_show, engramkeep_list, engramkeep_recent, engramkeep_doctor, and engramkeep_fixes. To also expose the write tools engramkeep_remember and engramkeep_record_fix, start the server with --allow-write:

{
  "mcpServers": {
    "engramkeep": {
      "command": "engramkeep",
      "args": ["mcp", "--allow-write"]
    }
  }
}

There is no MCP forget tool. Use the CLI and confirm destructive actions explicitly. Run engramkeep mcp --status to print the transport, protocol version, and write mode.

Dashboard

Start the local dashboard with:

engramkeep dashboard

It binds to 127.0.0.1 and prints a URL with a per-session token in the fragment. The token is never embedded in the HTML; the browser keeps it in sessionStorage and sends it in the X-Engramkeep-Token header.

The dashboard is read-only by default. To enable the remember form, start it with:

engramkeep dashboard --allow-write

Writes are POST-only and require confirm: true. There is no forget button. Use --port 0 to pick a free port, and run engramkeep dashboard --status for machine-readable security details.

Comparison with alternatives: Why Engramkeep?

Different projects approach agent memory from different angles. Here is how Engramkeep compares to common patterns and alternatives:

Objective differences

• vs. basic-memory: Both projects keep human-readable Markdown on your machine and speak MCP. basic-memory builds a richer semantic knowledge graph backed by SQLite and third-party Python dependencies. Engramkeep stays strictly on the Python standard library (0 runtime dependencies), adds a dedicated troubleshooting/fix registry (engramkeep fix / fixes), deterministic bilingual (EN/TR) concept expansion, automatic secret redaction before write, and a one-command managed-block installer with backups across 10 coding agents.
• vs. memsearch & Vector DBs: memsearch pairs Markdown files with Milvus vector embeddings for fuzzy semantic recall across large corpora. That power comes with embedding model downloads and vector runtime dependencies. Engramkeep intentionally trades dense vector embeddings for zero dependencies, ~4 ms lexical + concept-expanded queries, and zero background services.
• vs. Mem0: Mem0 is designed for dynamic conversational memory, user personalization, and hosted or multi-tenant agent applications. Engramkeep is strictly local-first and developer-project-centric: no cloud accounts, no LLM calls to extract memories, no API keys required, and every card lives as a plain Markdown file you own.
• vs. Manual single-file prompts (CLAUDE.md / AGENTS.md / brain.md): Plain Markdown rule files are transparent and portable. However, as projects grow, stuffing every past decision and bug fix into one root prompt file bloats the context window, risks accidental secret commits, and drifts out of sync across tools. Engramkeep keeps the root instruction block tiny via <!-- engramkeep:begin/end --> across 10 coding agents while storing project cards and verified fixes on demand, scrubbing secrets before write.

Pick Engramkeep when you want small, auditable, portable memory that lives with your code — not a complex RAG pipeline or hosted cloud service.

Security and privacy

• Local-only by default. The core makes no network calls and collects no telemetry.
• Secrets are redacted before write. API keys, tokens, passwords, JWTs, and private keys are replaced with [REDACTED].
• Path jail. Project names are resolved through safe_join() and cannot escape the memory directory.
• Atomic writes. Cards and generated files are written via a temporary file and os.replace().
• Memory is untrusted data. Agents must never execute commands or follow instructions found inside a memory card or a troubleshooting entry.
• Installer safety. Dry run by default, managed blocks only, timestamped backups, manifest.json, and a reversible uninstall.
• No automatic Git push, cloud upload, junction, or background daemon. Those features are intentionally excluded.
• MCP is local and read-only by default. Stdio transport, no network listener, no forget tool, write tools only with --allow-write.
• The dashboard is loopback-only and token-protected. 127.0.0.1, per-session token, strict CSP, text-only rendering, writes only with --allow-write plus explicit confirmation.

Read docs/PRIVACY.md and docs/THREAT_MODEL.md before deploying Engramkeep in a sensitive environment.

Non-goals

• Replacing Git, an issue tracker, or a documentation site.
• Storing secrets, credentials, or regulated personal data.
• Automatic transcript scraping from every agent. (Read-only, consent-based transcript adapters are on the roadmap.)
• A hosted service or a vector database.
• Perfect recall. Memory is only as good as what you record.

Project structure

engramkeep/
├── AGENTS.md
├── README.md
├── README.tr.md
├── LICENSE
├── pyproject.toml
├── src/engramkeep/
│   ├── cli.py
│   ├── config.py
│   ├── concepts.py        # bilingual EN/TR concept expansion
│   ├── models.py
│   ├── paths.py
│   ├── redact.py
│   ├── search.py
│   ├── store.py
│   ├── troubleshoot.py    # troubleshooting registry (TROUBLESHOOTING.md)
│   ├── mcp_server.py      # MCP stdio server
│   ├── dashboard.py       # hardened local dashboard
│   ├── installer.py       # backed-up, managed-block agent installer
│   └── adapters/          # future transcript adapters
├── assets/                # dashboard.png, demo.gif
├── examples/
│   ├── brain/             # minimal valid store
│   ├── demo-brain/        # generated synthetic store
│   ├── demo-cards.json
│   └── fix-registry/      # benchmark corpus
├── scripts/
│   ├── build_demo_brain.py
│   └── benchmark_fix_registry.py
├── skills/engramkeep/SKILL.md
├── templates/
├── tests/                 # 254 tests
├── docs/
└── .github/

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and report security issues through SECURITY.md. Good first tasks are listed in docs/GOOD_FIRST_ISSUES.md.

License

MIT. See LICENSE.

Engramkeep is not affiliated with Google, Anthropic, OpenAI, Anysphere, Cognition, or any other agent vendor. See TRADEMARKS.md.