Piia Engram is a local-first AI work identity and memory layer from an individual-led open-source project (AGPL-3.0), not an Anthropic or MCP-official offering. Its positioning is deliberate and clearly differentiated from agent task-memory stores such as Mem0, Zep, and Letta: it stores who you are — identity, preferences, quality standards, lessons, and decisions — rather than what happened in one workflow. Data lives as plaintext JSON/Markdown under ~/.engram/, with zero network calls by default and no cloud account, so you can open, edit, back up, or migrate it yourself. Nineteen core tools load by default, with ENGRAM_TOOLS=all unlocking all 59; writes pass through a tiered governance and staging model where high-risk content needs human approval and strict mode can gate everything. Cross-tool continuity is backed by a verifiable evidence path (a documented Claude Code → Codex continuity proof plus a synthetic MCIC benchmark), and a read-only Preview/Memory Lens shows exactly what a caller would receive. Its boundaries are stated just as honestly: plaintext storage by default, caller identity from environment variables rather than strong authentication, governance as a local policy layer rather than a hardened sandbox, and an explicit warning not to store keys or customer PII. A strong fit for individual developers who juggle multiple MCP coding tools and value local data sovereignty; a poor fit for teams needing shared memory, enterprise support, or a commercial license.
Strongest · Setup experience 14/20 Weakest · Reliability 10/20
Static review · not runListed 2026-09-10
Read the FMRS scoring method →Runtime：Python 3.10+
ENGRAM_SECRET
Local passphrase for optional field-level AES-256-GCM encryption, chosen by the user; requires pip install piia-engram[secure].
ENGRAM_AUTH_TOKEN
Bearer token for remote SSE mode, generated locally via secrets.token_urlsafe(32).
ENGRAM_MCP_STARTUP_SYNC
Controls local startup sync for the MCP server; set to off to skip it, background is the default.
ENGRAM_TOOLS
Controls the exposed tool surface; default core (19 tools), set to all for the full 59-tool advanced surface.
PYTHONIOENCODING
Forces UTF-8 stdio frames on Windows-style consoles; set to utf-8.
ENGRAM_APPROVAL
Write-approval policy; set to strict to gate every write behind human review.
ENGRAM_SEARCH
Search mode; set to hybrid to enable FTS5 + vector hybrid retrieval (requires pip install "piia-engram[vector]").
ENGRAM_GOVERNANCE
Enables per-caller trust-level governance; set to 1 to turn on.
ENGRAM_CLIENT_TYPE
Declares caller identity when governance is on, e.g. claude_code.
ENGRAM_AUDIT
Local audit log toggle; set to 0 to disable writing ~/.engram/audit.log.
ENGRAM_EPHEMERAL
Set to 1 in container/ephemeral clients to skip startup sync and migration work.
ENGRAM_CORS_ORIGINS
Restricts cross-origin access in remote deployments, e.g. https://your-domain.com.
Option 1 (pip): run pip install piia-engram && engram setup. The wizard detects your Python environment, lets you choose the Engram data folder (~/.engram, another drive, or a custom path), detects your AI tools and lists the exact config files it will touch, and writes the MCP connection only after a one-keystroke confirm (every write is backed up first; decline and nothing changes). It then walks you through seed knowledge (role, tech stack, language), can smart-import rules from existing CLAUDE.md / .cursorrules files, and previews your AI identity card.
Option 2 (uvx, no prior install): use uvx --from piia-engram piia-engram-mcp in your client config.
Client config example (Claude Desktop / generic MCP over stdio):
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}Cursor uses ~/.cursor/mcp.json, Codex uses ~/.codex/mcp.json, Claude Desktop uses claude_desktop_config.json. Claude Code also supports claude mcp add piia-engram -- piia-engram-mcp.
For non-interactive or CI runs, engram setup --apply-external-config skips the confirmation prompt (backups are still taken). Restart your AI tool afterwards and run engram doctor to verify connectivity.
Optional environment variables: ENGRAM_TOOLS=core|all (default core exposes the 19 core tools; all unlocks the full 59), ENGRAM_MCP_STARTUP_SYNC=off|background|eager (default off; background is for local cross-tool sync), PYTHONIOENCODING=utf-8 (Windows-style consoles).
Remote deployment: pip install piia-engram[remote], generate a token, then start ENGRAM_AUTH_TOKEN=... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767. Clients connect with a url plus an Authorization: Bearer header; always put it behind TLS in production.
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}
Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.
{
"servers": {
"piia-engram": {
"command": "python",
"args": [
"-m",
"piia_engram.mcp_server"
]
}
}
}
Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).
claude mcp add piia-engram -- python -m piia_engram.mcp_server
Run it in a terminal; replace any <…> placeholders with your own values first.
Run engram doctor to confirm your tools are detected and configured as healthy; the piia-engram tools (e.g. get_user_context) should appear in your client's tool list, and calling one should return your identity and knowledge context.
Once connected, you can ask your AI assistant things like:
No matching tools
Listed from the project's documentation, not tested by this site.
Piia Engram is a local-first AI work identity and memory layer for MCP-compatible coding tools such as Claude Code, Codex, Cursor, Windsurf, and Claude Desktop. You tell it once who you are, how you work, and what "good" means; multiple AI tools can then start from the same approved context — identity, preferences, quality standards, code-review bar, lessons learned, key decisions, and project snapshots — stored as plain JSON and Markdown under ~/.engram/ on your machine. There is no cloud account and no hidden memory you cannot inspect.
It deliberately occupies a different layer from agent task-memory databases like Mem0, Zep, or Letta: those store what happened during a workflow, while Piia Engram stores who is behind every task. It ships 59 MCP tools, but only 19 Tier-1 core tools are loaded by default to keep context clean; setting ENGRAM_TOOLS=all unlocks the full surface (knowledge management, governance, import/export, admin).
Writes follow a governance model: AI writes locally, high-risk items (credentials, shell commands, MCP config, permission rules) wait in staging for your review, and low/medium writes are auto-absorbed but fully auditable and reversible. ENGRAM_APPROVAL=strict gates every write. Other capabilities include cross-project knowledge inheritance, session-insight extraction, playbook auto-extraction (drafts only — you confirm before a playbook becomes trusted), a local tools registry, knowledge health and near-duplicate discovery, optional hybrid retrieval (FTS5 plus a semantic vector layer, off by default), optional field-level AES-256-GCM encryption, and a local audit log.
By default the identity and knowledge tools make zero network calls (except the optional read_web_content); telemetry is off by default, and remote telemetry or feedback requires separate explicit opt-in and sends counts only. Licensed AGPL-3.0, created by @Patdolitse with Claude Code and Codex as AI assistants — a community open-source project, not an Anthropic or MCP-official offering.
Upstash's official server providing up-to-date third-party library docs for AI coding assistants
AI-powered NPM package analysis MCP server
An independent control layer that gives AI coding agents budgets, brakes, and receipts
GitHub's official MCP server for managing repos, issues, PRs, and workflows via natural language
Source revision aafb8801a141 Data synced 2026-10-19 Read the FMRS scoring method