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

You  → "Help me refactor this auth module"

# WITHOUT piia-engram: AI starts from scratch
AI   → "What language? What framework? What's your testing preference?"

# WITH piia-engram: AI can load your approved identity and long-term knowledge
AI   → "Based on your preference for pytest + 90% coverage, and your
        lesson about always separating auth middleware from business
        logic (from the March incident), here's my approach..."

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

pip install piia-engram && engram setup

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:

pip install piia-engram
engram setup --non-interactive --json
engram setup --non-interactive --apply
engram doctor --json

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.

By the numbers

These are current repository facts from docs/public-facts.json. Public registries and package badges update only during release/publish.

Your AI forgets you every time you switch tools or start a new chat. piia-engram fixes the handoff.

Every time you open a new chat window, switch from Claude Code to Codex, u