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.

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
OpenClaw	SOUL.md / MEMORY.md / USER.md import and export	L3 static file-bridge evidence (static snapshot A/B only; live agent behavior unverified)
ChatGPT / Gemini / Kimi	Markdown identity card fallback	Usable
Windsurf	MCP over stdio	Expected to work
GitHub Copilot	MCP over stdio	Expected to work
Cline	MCP over stdio	Expected to work
Roo Code	MCP over stdio	Expected to work
Amazon Q	MCP over stdio	Expected to work
Augment	MCP over stdio	Expected to work
Zed	MCP over stdio	Expected to work
Trae	MCP over stdio	Expected to work
Tencent CodeBuddy	MCP over stdio	Expected to work

By the numbers

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

	Current repo / development facts
Version frame	v4.26.0 (verified 2026-10-21; check PyPI and GitHub Releases for the latest published package)
Supported AI tools	16 (evidence level varies by client; see Supported Tools and the validation runbook)
MCP tools	19 Core (loaded by default) + 40 Advanced (opt-in via ENGRAM_TOOLS=all)
Knowledge types	3 (lessons, decisions, playbooks)
Test suite	Unit + integration; run pytest tests/ to verify
Lines in core.py	1770 (facade; domain logic now lives in focused mixins — see architecture.md)
PBKDF2 iterations	600,000 (OWASP 2023+ floor; legacy 100k still decrypts)
Encryption	Optional field-level AES-256-GCM for supported profile fields; local files are plaintext JSON/Markdown by default
Cold-start time	< 100 ms typical (local JSON, no network)
Network calls by default	One anonymous usage ping a day (engram telemetry off or DO_NOT_TRACK=1 turns it off); the engram command also checks PyPI for a newer version at most once a day in interactive terminals, and engram doctor checks on each run (ENGRAM_NO_UPDATE_CHECK=1 turns it off); identity and knowledge tools make none, except the optional read_web_content; remote telemetry and feedback require separate explicit opt-in and send counts only (see privacy details)

---

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, update your AI tool, or move into a different project, you're back to zero:

• your communication preferences — gone
• your code standards and quality bar — forgotten
• which mistakes you've already learned from — lost
• why you made that architecture decision last month — erased

This happens because AI memory today is locked inside each platform. It belongs to the tool, not to you. The tool updates, resets, or gets replaced — and your context disappears with it.

piia-engram gives you a personal identity layer that lives on your machine, independent of any AI tool. You tell it once who you are, how you work, and what you've learned. MCP-compatible tools can read the same approved identity and long-term knowledge. New chat, new tool, new version — your identity stays portable.

piia-engram is not an agent memory database. Tools like Mem0, Zep, and Letta store task context and session history for AI agents. piia-engram stores who you are as a person — your identity, preferences, hard-won lessons, and key decisions. It's a different layer: not what happened in a task, but who is behind every task.

Why piia-engram?

Without piia-engram	With piia-engram
New chat window = start from zero	Configured conversations can load your approved identity and long-term knowledge
AI tool updates and your preferences vanish	Your identity lives on your machine, survives any update
Switching tools loses accumulated context	Claude Code, Codex, and Cursor read the same memory
Past mistakes get repeated	Lessons learned follow you across tools and sessions
Memory is locked inside one product	Data stays local, editable, and portable

Who Uses piia-engram

piia-engram is built for developers who use multiple AI coding tools and are tired of re-explaining themselves.

If you switch between Claude Code, Codex, and Cursor — your code standards, architecture decisions, and hard-won lessons reset every time. piia-engram makes every tool start from the same understanding of who you are.

If you open 10+ AI chat windows a week — each one starts from zero. piia-engram lets each conversation start from the same approved identity and knowledge context.

If you've lost preferences after a tool update — your identity lives on your machine, not inside any platform. Updates, resets, and migrations don't touch your memory.

Investment analysts Decisions get made but reasoning gets lost. piia-engram stores the full reasoning chain so six months later, "why did I pass on that?" has a real answer — and your analytical framework travels with you across every new analysis.

System architects Architecture decisions need context: what you chose, what you ruled out, and why. piia-engram keeps living Architecture Decision Records that travel with you across companies and projects, queryable by any AI tool.

Backend developers API quirks, integration gotchas, performance trade-offs — tacit knowledge that normally lives in your head and resets when you change jobs. piia-engram turns it into a searchable library that persists across everything.

Frontend and design Design philosophy rarely gets documented in a way AI tools can use. piia-engram stores your real standards, UX lessons from real users, and the reasoning behind component decisions — so every project starts where your last one ended.

Vibe coders You build with AI and move fast. The problem: every new session your AI starts from scratch — different style choices, inconsistent patterns, re-explaining the same preferences. piia-engram makes every tool consistent from session one: your stack, your patterns, your voice, already there.

What piia-engram Stores

All data lives under ~/.engram/ as plain JSON and Markdown files you can open, edit, back up, or migrate yourself.

• Identity: who you are, how you communicate, what languages you prefer
• Quality standards: your code review bar, test coverage expectations, what you refuse to ship
• Preferences: coding style, AI behavior, how you like explanations
• Trust boundaries: which fields to keep private, what tools can access
• Project snapshots: context for ongoing work, captured and reloadable
• Lessons learned: mistakes, surprises, things that worked and didn't
• Key decisions: what you chose, what you ruled out, and why
• Domain knowledge: reusable insights across projects and tools

What piia-engram Does (Beyond Storage)

Most memory tools are passive — you put things in, they give them back. piia-engram is also active.

Knowledge inheritance across projects
Describe a new project in plain text. get_knowledge_inheritance returns a curated starter pack of the most relevant lessons and decisions from everything you have ever worked on. Your tenth project benefits from all nine before it — one tool call away.

Passive knowledge capture
Paste a session summary into extract_session_insights and piia-engram extracts and stores the lessons and decisions. No manual note-taking. Knowledge accumulates through normal AI conversations.

Works with tools that do not support MCP
ChatGPT, Gemini, Kimi — get_identity_card exports a ready-to-paste Markdown identity card. Your context travels even to tools that cannot connect directly.

Automatic playbook extraction
Finish a multi-step workflow — release to PyPI, deploy to Cloudflare, publish to MCP Registry — and piia-engram detects it at session end. It generates a structured draft playbook (steps, pitfalls, trigger keywords) and saves it to a staging area. Next time you do the same task, the AI can retrieve the confirmed playbook as a passive reference, walk through the steps with you, and record the outcome. No manual recording required — Engram starts the draft, you confirm, the host AI stays accountable. See Playbook Auto-Extraction below.

Local tools registry
AI tools constantly search for local programs, runtimes, and CLIs. register_tool records what's installed and where; find_tool retrieves it instantly. No more which python every session — the environment map persists across tools and conversations.

Knowledge health and discovery
get_knowledge_overview surfaces stale lessons (not reviewed in 30+ days), computes a 0–100 health score across four dimensions (freshness, quality, coverage, cleanliness), and flags gaps worth revisiting. explore_knowledge scans your knowledge base for near-duplicates (and walks related/similar items) with actionable merge commands. manage_relation connects related lessons and decisions into a navigable knowledge graph.

Hybrid search (optional, off by default)
The default keyword search stays unchanged. Opt in to hybrid retrieval — FTS5 full-text plus a semantic vector layer — for cross-lingual recall, e.g. an English query finding a Chinese note: pip install "piia-engram[vector]" and set ENGRAM_SEARCH=hybrid, or let engram setup enable it with one keystroke. The index is a rebuildable SQLite file; your JSON store remains the single source of truth. See docs/hybrid-search.md.

Quick Start

pip install piia-engram
engram setup

New to piia-engram? See the fuller first-value quickstart for the install -> first memory -> fresh-session recall path using only the default 19 core tools, or the complete User Guide covering install -> first value -> cross-tool continuity -> governance -> privacy -> FAQ. Host-specific setup cards are available for Claude Code, Codex, and Cursor. For proposal-only safe-context, replay, freshness/conflict, and evidence drafts, see Context governance.

The setup wizard will:

1. Detect your Python environment
2. Let you choose the Engram data folder (~/.engram, another drive, or a custom path)
3. Detect your AI tools, list the exact config files it will touch, and write the MCP connection after a one-keystroke confirm (backed up first; decline leaves them untouched)
4. Walk you through seed knowledge (role, tech stack, language)
5. Offer to import rules and memories from your other AI tools — CLAUDE.md, .cursorrules, memory files (default no; lists them first, then the review queue, approve with engram review)
6. Show a short daily usage ping notice; neither setup mode asks about telemetry or changes your choices
7. Preview your AI identity card — immediate proof of value

After setup writes the MCP connection (you confirm at the prompt first), restart your AI tool. Many clients can call get_user_context at startup; when a host does not do that proactively, an explicit search_knowledge or get_resume_brief call is still the expected L2 path.

For non-interactive or CI runs, skip the confirmation prompt and write directly:

engram setup --apply-external-config

Either way, every external config write is backed up under the selected Engram data folder, and declining the prompt leaves every external config untouched.

For point-and-click local review, open piia-engram-review (double-click its installed Windows launcher). Review complete proposals and choose approve, reject or later, with optional body-free prompts while the window is running. Python with Tk support is required; MCP approval permissions stay unchanged. See the local review window guide.

Check health anytime:

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
engram preview --as automation  # see exactly what a given AI caller would receive (read-only)
engram continuity    # metadata-only proof that cross-tool handoff is ready
engram management    # metadata-only review/playbook management view
engram doctor        # diagnose all tools
engram doctor --fix  # auto-repair issues + inject missing instructions
engram doctor --days 7 --json  # which AI clients are configured and called Engram lately (read-only)
engram repair-encoding        # dry-run scan for garbled / mojibake text
engram repair-encoding --apply  # repair reversible cases with a backup

engram continuity is metadata-only: it reports saved-session counts, contributing tools, resume-brief readiness, and aggregate context-load / wrap-up signals without printing memory bodies, raw telemetry events, session IDs, or local paths.

For a machine-readable synthetic loop proof, run:

python demos/cross_tool_continuity_demo.py --json

engram continuity reports readiness metadata. The demo JSON proves an isolated write -> resume -> search -> provenance loop using synthetic data only.

Replay experience mode

Automated offline and online evaluation callers can use IsolatedStore.admit(..., event_key="source:event:record:v1") in either isolated mode to distinguish events with identical text and retry the same event safely. Recall returns a ledger-backed receipt with a snapshot identifier, ordered IDs, content hashes and effective filters; verify_recall_receipt reports later changes without bodies. Replay callers may also supply effective_at and now to retire/restore at historical times. An Owner veto hides a card at every time.

Pin the isolated store API with from piia_engram.isolated_store import require_contract; require_contract("1") before opening a store. Contract v1 supports admit(..., supersedes=item_id) to admit a replacement and deactivate its predecessor in one completion receipt, with crash-safe retries in both modes. Family, subject and the exact opaque source_decision_point must match. An active version blocks restoration of another version; rollback appends a new version. Recall also returns and seals a deterministic result_sha256 over effective cuts, exclusion counts and ordered content references. Incompatible changes require a new contract version, with continued support or contract_version_unsupported; existing ledgers remain readable.

Offline replays and evaluations that re-feed historical material in chronological order can initialize an isolated store with "mode": "replay_experience" in its launcher configuration. The root mode is immutable. Admission requires timezone-aware admitted_before and now parameters; recall also requires now. Historical admission uses the supplied time while receipts keep real timestamps, and automatic same-family exclusion is disabled. Evidence still stops at the decision point's as_of. Replay admission keeps nonidentical normalized summaries verified even when template similarity is high; exact duplicates and existing tombstone, retired and archived twin rules still apply. Without event keys, production duplicate handling is unchanged; all capacity limits still apply. Replay roots may pin hard_cap up to 10,000 (for example, 1,400); production roots retain the 1,000 default. Native backups and returned entries carry store_mode: replay_experience, and ordinary roots refuse replay roots and marked imports.

The separation prevents accidental mixing, such as using the wrong configuration, attaching another root, or importing an unmarked export. New initialization receipts are bound to the directory identity, and context text retains its replay marker. This is not a tamper-proof boundary against someone who can edit both roots and their ledgers. Existing production roots created before replay mode retain direct attachment without launcher configuration.

For broader release evidence, run the synthetic MCIC benchmark:

python demos/mcic_benchmark.py --json