piia-engram
One memory. Every AI tool. Yours to keep.
AI can suggest memories. You decide what becomes true.
Tell AI once — your preferences, standards, and lessons follow you across Claude Code, Cursor, Codex, and any MCP-compatible tool. AI proposes knowledge; you approve what sticks. Local-first, no cloud, no account.
cross-tool memory | local-first | Claude Code | Codex | Cursor | Windsurf | MCP
TL;DR: piia-engram stores your identity, preferences, lessons learned, and key decisions as local JSON files — and shares them with every AI tool through MCP. Set up once, every AI tool remembers you. No cloud, no lock-in, Apache 2.0.
Your AI forgets you every time you switch tools or start a new chat. piia-engram fixes that.
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 persistent memory 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. Every MCP-compatible tool reads the same context. New chat, new tool, new version — your identity persists.
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 | Every conversation already knows you | | 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 gives every conversation your full context from the first message.
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 finds the playbook and follows it, skipping the mistakes you already solved. No manual recording required — Engram starts the draft, you confirm, AI completes. 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. suggest_merges scans your entire knowledge base for near-duplicates and returns actionable merge commands. link_knowledge connects related lessons and decisions into a navigable knowledge graph.
Quick Start (30 seconds)
pip install piia-engram
engram setup
The setup wizard will:
- Detect your Python environment
- Find and configure your AI tools (Claude Code, Cursor, Claude Desktop, Codex)
- Inject AI instructions into each tool's native config (
CLAUDE.md,.cursorrules,AGENTS.md) so AI proactively calls Engram - Walk you through seed knowledge (role, tech stack, language)
- Smart-import rules from your existing
CLAUDE.md/.cursorrulesfiles - Show your privacy preferences (cross-tool sync, anonymous statistics — both optional)
- Preview your AI identity card — immediate proof of value
Restart your AI tool after setup. The first conversation will call get_user_context automatically — your AI already knows you.
Check health anytime:
engram doctor # diagnose all tools
engram doctor --fix # auto-repair issues + inject missing instructions
Configure for Your AI Tool
# Automatic (recommended)
engram setup
# Or manual:
claude mcp add piia-engram -- python -m piia_engram.mcp_server
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}
Add to ~/.codex/mcp.json:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}
Add to `cla