Patdolitse/piia-engram

Local-first AI work identity you can see, edit, and override — portable across your MCP coding tools.
Tell AI once who you are, how you work, and what "good" means.
Claude Code, Codex, Cursor, Windsurf, and other MCP-compatible tools can start from the same AI work identity layer — local files you own, no cloud account, no hidden memory you cannot inspect.
Install · See It in Action · Supported Tools · MCP Tools · FAQ
ENGLISH | 中文
**Listed in:**
Also listed in: awesome-agents · Awesome-MCP-ZH · mcpservers.org · Cursor Directory · ModelScope · PulseMCP
---
> **TL;DR:** piia-engram is a local-first personal AI identity layer. It helps multiple coding agents start from the same understanding of you: your preferences, quality bar, lessons learned, decisions, and project context. It is not an agent memory database; it is the user-owned layer above your tools.
**Why not just use native memory?** Claude Code, Codex, Cursor, and Windsurf are adding their own memories and rules. Those are useful, but they are scoped to one tool or workspace. piia-engram gives you one portable identity layer above them: local files you own, AI-proposed knowledge you review, and context that can follow you across tools.
**Trust model in four lines:**
- **No cloud account:** install with pip, keep the core store on your machine.
- **Local files:** identity and knowledge live under ~/.engram/ as JSON/Markdown.
- **User approval:** AI writes locally; high-risk items (credentials, shell commands, MCP config, permission rules) wait for your review, while low/medium writes are auto-absorbed but fully auditable and reversible. Set ENGRAM_APPROVAL=strict to gate every write. "Verified" means accepted by you or by that policy, not re-checked against your current code.
- **Session continuity:** Resume output can also include earlier session records (checkpoints and snapshots) that are not reviewed and do not authorize actions. Approval and review claims apply to identity and long-term knowledge under the configured policy.
- **Documented boundaries:** see Trust model, Privacy, and Security.
Want proof? See the live cross-tool continuity proof — a memory written by Claude Code, read back by Codex through one local store — or the one-command reproducible code demo.
See It in Action
And you never have to take that on faith — **Memory Lens** (engram preview --html) shows exactly what any AI caller would receive, and what governance withheld, before anything is sent:
*Above: a real report from a demo store — 4 items exposed; an unreviewed staging note and a lesson containing a credential are withheld, with the secret shown as [REDACTED].*
---
Install
The wizard auto-detects your AI tools — Claude Code, Cursor, Codex, Claude Desktop — lists the exact config files it will touch, and writes the MCP connection after a one-keystroke confirm (every write is backed up first; decline and nothing changes). It previews your identity card, then you restart your configured tool; the first conversation can load your approved identity and long-term knowledge through startup or search tools. (full walkthrough ↓)
---
Let your AI agent install it
Ask your coding agent to install Engram and inspect the plan before applying:
Setup asks no questions. Use --clients cursor,codex to limit clients and
--lang zh|en for output language (default en). Without --apply, plan mode
writes nothing to the Engram store, home directory or client configs. Python
itself may use the system temporary directory. Apply configures MCP connections
with backups, preserves existing tool modes, and never imports memories, writes
identity/knowledge, or approves proposals. Restart configured clients; exit code
1 means a manual step remains. See llms.txt for agent instructions and
the CLI and JSON contract for details.
Supported Tools
Evidence levels follow the agent client validation runbook: L0 = discovery, L1 = protocol access, L2 = read/search behavior, L3 = A/B behavior gain, L4 = cross-client continuity, L5 = reproducible public evidence.
| Tool | Integration | Evidence status |
|---|---|---|
| Claude Code | MCP over stdio | L4 partial continuity proof (Claude Code -> Codex) |
| Codex | MCP over stdio | L4 partial continuity proof (Claude Code -> Codex) |
| Cursor | MCP over stdio | L2 setup/read-search evidence path |
| Claude Desktop | MCP over stdio | L1/L2 setup path; client-specific evidence pending |
| Hermes | MCP over stdio | L4 controlled CLI marker continuity; desktop and broad benchmark claims unverified |