[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-78379":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":15,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":45,"readmeContent":46,"aiSummary":47,"trendingCount":16,"starSnapshotCount":16,"syncStatus":48,"lastSyncTime":49,"discoverSource":50},78379,"piia-engram","Patdolitse\u002Fpiia-engram","Patdolitse","Local-first AI memory you can see, edit, and override — portable across Claude Code, Codex, Cursor, Windsurf, and other MCP coding tools.","https:\u002F\u002Fpypi.org\u002Fproject\u002Fpiia-engram\u002F",null,"Python",164,9,66,1,0,3,89,53.4,"Apache License 2.0",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"ai-agent","ai-identity","ai-identity-layer","ai-tools","anthropic","claude-code","claude-desktop","codex","context-management","cross-tool-context","cursor","developer-tools","llm-tools","local-first","mcp","mcp-server","model-context-protocol","personal-ai","python","windsurf","2026-06-12 04:01:23","\u003C!-- mcp-name: io.github.Patdolitse\u002Fpiia-engram -->\n\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"assets\u002Fsocial_preview.png\" alt=\"piia-engram — persistent AI memory across tools\" width=\"640\">\n\n# piia-engram\n\n### One memory. Every AI tool. Yours to keep.\n\n### AI can suggest memories. You decide what becomes true.\n\n**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.**\n\n`cross-tool memory` | `local-first` | `Claude Code` | `Codex` | `Cursor` | `Windsurf` | `MCP`\n\n[ENGLISH](README.md) | [中文](README.zh-CN.md)\n\n[![License: Apache 2.0](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-Apache%202.0-blue.svg)](LICENSE)\n[![Python 3.10+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-blue.svg)](https:\u002F\u002Fpython.org)\n[![MCP Compatible](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Compatible-purple.svg)](https:\u002F\u002Fmodelcontextprotocol.io)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fpiia-engram)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fpiia-engram\u002F)\n[![Downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fpiia-engram)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fpiia-engram\u002F)\n[![Official MCP Registry](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP_Registry-official-green.svg)](https:\u002F\u002Fregistry.modelcontextprotocol.io)\n\n\u003C\u002Fdiv>\n\n---\n\n> **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.\n\n---\n\n**Your AI forgets you every time you switch tools or start a new chat.** piia-engram fixes that.\n\nEvery 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:\n\n- your communication preferences — gone\n- your code standards and quality bar — forgotten\n- which mistakes you've already learned from — lost\n- why you made that architecture decision last month — erased\n\nThis 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.\n\n**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.\n\n> **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.\n\n## Why piia-engram?\n\n| Without piia-engram | With piia-engram |\n|---|---|\n| New chat window = start from zero | Every conversation already knows you |\n| AI tool updates and your preferences vanish | Your identity lives on your machine, survives any update |\n| Switching tools loses accumulated context | Claude Code, Codex, and Cursor read the same memory |\n| Past mistakes get repeated | Lessons learned follow you across tools and sessions |\n| Memory is locked inside one product | Data stays local, editable, and portable |\n\n## Who Uses piia-engram\n\npiia-engram is built for developers who use multiple AI coding tools and are tired of re-explaining themselves.\n\n**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.\n\n**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.\n\n**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.\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Other use cases\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Investment analysts**\nDecisions 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.\n\n**System architects**\nArchitecture 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.\n\n**Backend developers**\nAPI 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.\n\n**Frontend and design**\nDesign 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.\n\n**Vibe coders**\nYou 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.\n\n\u003C\u002Fdetails>\n\n## What piia-engram Stores\n\nAll data lives under `~\u002F.engram\u002F` as plain JSON and Markdown files you can open, edit, back up, or migrate yourself.\n\n- **Identity**: who you are, how you communicate, what languages you prefer\n- **Quality standards**: your code review bar, test coverage expectations, what you refuse to ship\n- **Preferences**: coding style, AI behavior, how you like explanations\n- **Trust boundaries**: which fields to keep private, what tools can access\n- **Project snapshots**: context for ongoing work, captured and reloadable\n- **Lessons learned**: mistakes, surprises, things that worked and didn't\n- **Key decisions**: what you chose, what you ruled out, and why\n- **Domain knowledge**: reusable insights across projects and tools\n\n## What piia-engram Does (Beyond Storage)\n\nMost memory tools are passive — you put things in, they give them back. piia-engram is also active.\n\n**Knowledge inheritance across projects**  \nDescribe 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.\n\n**Passive knowledge capture**  \nPaste 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.\n\n**Works with tools that do not support MCP**  \nChatGPT, Gemini, Kimi — `get_identity_card` exports a ready-to-paste Markdown identity card. Your context travels even to tools that cannot connect directly.\n\n**Automatic playbook extraction**  \nFinish 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](#playbook-auto-extraction) below.\n\n**Local tools registry**  \nAI 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.\n\n**Knowledge health and discovery**  \n`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.\n\n## Quick Start (30 seconds)\n\n```bash\npip install piia-engram\nengram setup\n```\n\nThe setup wizard will:\n1. Detect your Python environment\n2. Find and configure your AI tools (Claude Code, Cursor, Claude Desktop, Codex)\n3. **Inject AI instructions** into each tool's native config (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`) so AI proactively calls Engram\n4. Walk you through seed knowledge (role, tech stack, language)\n5. Smart-import rules from your existing `CLAUDE.md` \u002F `.cursorrules` files\n6. Show your privacy preferences (cross-tool sync, anonymous statistics — both optional)\n7. **Preview your AI identity card** — immediate proof of value\n\nRestart your AI tool after setup. The first conversation will call `get_user_context` automatically — your AI already knows you.\n\nCheck health anytime:\n```bash\nengram doctor        # diagnose all tools\nengram doctor --fix  # auto-repair issues + inject missing instructions\n```\n\n### Configure for Your AI Tool\n\n\u003Cdetails open>\n\u003Csummary>\u003Cstrong>Claude Code\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```bash\n# Automatic (recommended)\nengram setup\n# Or manual:\nclaude mcp add piia-engram -- python -m piia_engram.mcp_server\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Cursor\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdd to `~\u002F.cursor\u002Fmcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"piia_engram.mcp_server\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Codex (OpenAI)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdd to `~\u002F.codex\u002Fmcp.json`:\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"piia_engram.mcp_server\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Claude Desktop\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAdd to `claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"piia_engram.mcp_server\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Windsurf \u002F Copilot \u002F Cline \u002F Other MCP clients\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nAny tool that supports MCP over stdio works. Use this config:\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"piia_engram.mcp_server\"]\n    }\n  }\n}\n```\n\nFor tools without MCP support (ChatGPT, Gemini, Kimi): run `get_identity_card` in any MCP tool and paste the exported Markdown card into your chat.\n\n\u003C\u002Fdetails>\n\n### See It in Action\n\n```\nYou  → \"Help me refactor this auth module\"\n\n# WITHOUT piia-engram: AI starts from scratch\nAI   → \"What language? What framework? What's your testing preference?\"\n\n# WITH piia-engram: AI already knows you\nAI   → \"Based on your preference for pytest + 90% coverage, and your\n        lesson about always separating auth middleware from business\n        logic (from the March incident), here's my approach...\"\n```\n\nAfter setup, run `engram doctor` to verify everything is connected:\n\n```\n$ engram doctor\n\n  Detected 3 AI tool(s):\n    [ok] Claude Code — Engram configured\n    [ok] Cursor — Engram configured\n    [ok] Codex — Engram configured\n\n  [ok] All configured tools look healthy.\n\n  ── Functional Checks ──\n    [ok] piia_engram.core importable\n    [ok] Engram initialized (~\u002F.engram)\n    [ok] Identity loaded (role: Senior Backend Developer)\n    [ok] quick_context.md ready (4096 bytes)\n    [ok] MCP server: 17 tools registered\n```\n\n\n## Upgrading\n\n```bash\npip install --upgrade piia-engram\n```\n\nAfter upgrading, piia-engram automatically migrates any stale MCP configs the next time its server starts (stdio mode). If your AI tool still shows an \"MCP disconnected\" error after restarting, run:\n\n```bash\npiia-engram doctor        # show what's wrong\npiia-engram doctor --fix  # auto-repair and fix in one step\n```\n\nThen restart the affected AI tool. The doctor command checks Claude Code, Cursor, and Claude Desktop configs and removes any outdated server entries.\n\n## Remote Deployment\n\nRun piia-engram on your own server and connect from anywhere.\n\n### Server Setup\n\n```bash\n# Install with remote support\npip install piia-engram[remote]\n\n# Generate an auth token\npython -c \"import secrets; print(secrets.token_urlsafe(32))\"\n# Save the output, e.g. \"abc123...\"\n\n# Start in SSE mode\nENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767\n```\n\n### Client Config (Claude Code)\n\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"url\": \"http:\u002F\u002Fyour-server:8767\u002Fsse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer abc123...\"\n      }\n    }\n  }\n}\n```\n\n### Client Config (Cursor)\n\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"url\": \"http:\u002F\u002Fyour-server:8767\u002Fsse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer abc123...\"\n      }\n    }\n  }\n}\n```\n\n**Security notes:**\n- Always use HTTPS in production, behind nginx or caddy with TLS.\n- The auth token protects your identity data. Keep it secret.\n- Default bind is `127.0.0.1` for localhost only. Use `0.0.0.0` only behind a reverse proxy.\n- Set `ENGRAM_CORS_ORIGINS` to restrict cross-origin access (e.g. `https:\u002F\u002Fyour-domain.com`).\n- Data stays on your server and never touches third-party clouds.\n\n## MCP Tools\n\npiia-engram ships 60 MCP tools. By default, only the 12 **Tier-1 Core** tools are loaded to keep the AI's context clean. To unlock all 60 tools, add `ENGRAM_TOOLS=all` to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"piia-engram\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"piia_engram.mcp_server\"],\n      \"env\": { \"ENGRAM_TOOLS\": \"all\" }\n    }\n  }\n}\n```\n\n### Tier-1 Core (12 tools — daily workflow)\n\n| Tool | Purpose |\n|---|---|\n| `get_user_context` | Load identity + knowledge at session start |\n| `wrap_up_session` | Save insights + sync at session end |\n| `add_lesson` | Store a reusable lesson learned |\n| `add_decision` | Record a key decision with reasoning |\n| `add_playbook` | Record an operational playbook (multi-step procedure with trigger keywords) |\n| `search_knowledge` | Search lessons, decisions, and playbooks by weighted relevance |\n| `get_relevant_knowledge` | Find knowledge relevant to current project |\n| `get_identity_card` | Export Markdown identity card for non-MCP tools |\n| `update_identity` | Update profile, preferences, or quality standards |\n| `get_project_context` | Read a saved project snapshot |\n| `save_project_snapshot` | Persist project state for future sessions |\n| `get_recent_context` | Recover lost session context after restart |\n\n### Tier-2 Advanced (48 tools — knowledge management, review, import\u002Fexport)\n\n\u003Cdetails>\n\u003Csummary>Click to expand full tool list\u003C\u002Fsummary>\n\n| Tool | Purpose |\n|---|---|\n| `register_tool` | Register a local tool, runtime, or CLI to the environment map |\n| `find_tool` | Look up a registered tool by name |\n| `list_tools` | List all registered tools (optionally filter by category) |\n| `save_agent_context` | Save AI session checkpoint (also runs automatically) |\n| `list_agent_sessions` | Browse saved session records across tools |\n| `refresh_quick_context` | Refresh local `quick_context.md` snapshot for offline\u002Fcross-tool use |\n| `get_profile` | Read user profile (safe=true by default) |\n| `get_work_style` | Read work style preferences |\n| `get_preferences` | Read communication and workflow preferences |\n| `get_trust_boundaries` | Read data access boundaries |\n| `get_quality_standards` | Read quality expectations |\n| `get_playbooks` | List saved operational playbooks |\n| `get_playbook` | Get full content of a single playbook by ID |\n| `get_recent_playbooks` | List playbooks by most recent use |\n| `update_playbook` | Update playbook steps, triggers, or other fields |\n| `archive_playbook` | Archive a playbook that is no longer used |\n| `prepare_playbook_execution` | Generate an executable plan with parameter substitution |\n| `update_execution_step` | Mark a step as completed, skipped, or failed |\n| `get_execution_status` | View current execution progress of a playbook |\n| `get_lessons` | List reusable lessons learned |\n| `get_decisions` | List key decisions and reasons |\n| `get_domains` | Read domain experience stats |\n| `get_knowledge_inheritance` | Build cross-project knowledge starter pack |\n| `list_projects` | List saved project snapshots |\n| `extract_session_insights` | Extract lessons and decisions from session text |\n| `bulk_add_knowledge` | Add multiple lessons or decisions in one call |\n| `ingest_notes` | Parse free-form notes into structured knowledge |\n| `update_knowledge` | Update a lesson or decision by ID |\n| `archive_knowledge` | Archive a lesson or decision by ID |\n| `review_knowledge` | Mark a knowledge item as reviewed |\n| `merge_knowledge` | Merge a duplicate into the primary item |\n| `link_knowledge` | Create a bidirectional link between items |\n| `unlink_knowledge` | Remove a bidirectional knowledge link |\n| `get_knowledge_overview` | Knowledge digest, health report, stale checks |\n| `get_related_knowledge` | Follow links between knowledge items |\n| `find_similar_knowledge` | Find similar items by content |\n| `suggest_merges` | Scan for near-duplicates with actionable merge commands |\n| `get_stale_knowledge` | List items that need review |\n| `export_knowledge_report` | Export a readable Markdown knowledge report |\n| `request_outline_review` | Generate an interactive HTML review page |\n| `apply_review` | Process review results (promote\u002Farchive staging items) |\n| `export_engram` | Export a full backup |\n| `import_engram` | Import a backup |\n| `export_engram_to_openclaw` | Export OpenClaw-compatible files |\n| `import_engram_from_openclaw` | Import OpenClaw-compatible files |\n| `read_web_content` | Read webpage via local Reader service |\n| `get_audit_log` | Get recent audit log entries |\n| `start_project` | Start a project with inherited knowledge |\n\n\u003C\u002Fdetails>\n\n## Playbook Auto-Extraction\n\npiia-engram can detect multi-step workflows you complete during a session and automatically draft structured playbooks — no manual recording required.\n\n### How It Works\n\n1. **Detection** — When you call `wrap_up_session` or `save_agent_context`, piia-engram scans for procedural workflow signals: checkpoint steps, action verbs, and trigger keywords.\n2. **Draft generation** — If a workflow is detected, a playbook draft is created with steps, pitfalls, trigger keywords, and preconditions. Sensitive information (API keys, tokens, absolute paths) is automatically redacted before storage.\n3. **Staging** — The draft is saved to a staging area, never auto-promoted to verified. You review and confirm before it becomes a trusted playbook.\n4. **Reuse** — Next time an AI tool encounters a similar task, `search_knowledge` matches the trigger keywords and returns the playbook. The AI follows the proven steps instead of improvising.\n\n### Design Philosophy: Engram Starts, You Confirm, AI Completes\n\nPlaybook auto-extraction is not fully automatic. piia-engram detects the workflow and generates a rough draft — but the draft stays in staging until you explicitly confirm it. Once confirmed, AI tools can refine and follow the playbook autonomously. This keeps humans in the loop for quality control while eliminating the manual work of writing operational procedures.\n\n### Confidence Levels\n\n| Level | Signal | AI Behavior |\n|---|---|---|\n| **high** | 3+ checkpoint steps from `save_agent_context` | AI notifies you: \"Detected a reusable workflow, draft playbook generated.\" |\n| **medium** | Text-based detection (trigger keywords + action verbs) | AI saves silently to staging, no notification. |\n\n### Sensitive Info Redaction\n\nBefore any draft is stored, piia-engram automatically redacts:\n- API keys and tokens (`Bearer`, `sk-`, `ghp_`, etc.)\n- Absolute file paths (Windows and Unix)\n- Email addresses\n- Environment variable secrets\n\n### Kill Switch\n\nUsers can disable or re-enable playbook auto-extraction at any time:\n\n- **Disable:** Tell your AI \"关闭 playbook\" \u002F \"stop playbook\" \u002F \"disable playbook auto-extraction\"\n- **Enable:** Tell your AI \"开启 playbook\" \u002F \"start playbook\" \u002F \"enable playbook auto-extraction\"\n\nThe AI calls `update_identity(field=\"preferences\", ...)` to toggle `playbook_auto_extract`. Default is **enabled**.\n\n### Manual Playbook Creation\n\nYou can always create playbooks manually with `add_playbook`, regardless of the auto-extraction setting. The kill switch only affects automatic detection during `wrap_up_session`.\n\n## Data Layout\n\n```text\n~\u002F.engram\u002F\n|-- schema_version.json\n|-- identity\u002F\n|   |-- profile.json\n|   |-- preferences.json\n|   |-- quality_standards.json\n|   `-- trust_boundaries.json\n|-- knowledge\u002F\n|   |-- lessons.json\n|   |-- decisions.json\n|   `-- domains.json\n|-- playbooks\u002F\n|   |-- _index.json\n|   `-- {playbook_id}.json\n|-- tools\u002F\n|   `-- registry.json\n|-- projects\u002F\n|   `-- {project_id}.json\n|-- contexts\u002F\n|   `-- {tool_name}\u002F\n|       `-- {session_id}.md\n|-- exports\u002F\n`-- compat\u002F\n    `-- openclaw\u002F\n```\n\n## Supported Tools\n\n| Tool | Integration | Confidence |\n|---|---|---|\n| Claude Code | MCP over stdio | ✅ Verified |\n| Codex | MCP over stdio | ✅ Verified |\n| Cursor | MCP over stdio | ✅ Verified |\n| Claude Desktop | MCP over stdio | ✅ Verified |\n| Windsurf | MCP over stdio | Expected to work |\n| GitHub Copilot | MCP over stdio | Expected to work |\n| Cline | MCP over stdio | Expected to work |\n| Roo Code | MCP over stdio | Expected to work |\n| Amazon Q | MCP over stdio | Expected to work |\n| Augment | MCP over stdio | Expected to work |\n| Zed | MCP over stdio | Expected to work |\n| OpenClaw | SOUL.md \u002F MEMORY.md \u002F USER.md import and export | ✅ Verified |\n| ChatGPT \u002F Gemini \u002F Kimi | Markdown identity card fallback | 🔧 Usable |\n\n## Comparison\n\n| Feature | piia-engram | Claude Memory | Manual `CLAUDE.md` | Mem0 | Letta (MemGPT) |\n|---|---|---|---|---|---|\n| Primary purpose | User identity across tools | Per-conversation memory | Per-project notes | Agent vector memory | Agent self-editing memory |\n| Cross-tool by design | ✅ MCP-native (60 tools) | ❌ Claude only | ❌ tool-specific | ⚠ requires per-tool wiring | ⚠ requires per-tool wiring |\n| Storage | Local JSON in `~\u002F.engram\u002F` | Cloud | Local | Vector DB + Mem0 Cloud | Postgres or Letta Cloud |\n| Local-first by default | ✅ | ❌ | ✅ | ⚠ Cloud is the default | ⚠ Cloud is the default |\n| Encryption at rest | ✅ AES-256-GCM, PBKDF2 600k (opt-in) | depends on Cloud | ❌ plain Markdown | depends on store config | depends on Postgres config |\n| Knowledge tiers (user gate) | ✅ staging → verified | ❌ | ❌ | ❌ | ❌ |\n| Conflict detection | ✅ | ❌ | ❌ | ❌ | ❌ |\n| MCP-native | ✅ | n\u002Fa | n\u002Fa | ⚠ third-party | ⚠ third-party |\n| Price | Free, Apache 2.0 | Subscription-bundled | Free | Free \u002F Cloud tiers | Free \u002F Cloud tiers |\n\n📊 **For the full side-by-side**, including when to choose a competitor over piia-engram, see [`docs\u002Fcomparison.md`](docs\u002Fcomparison.md).\n\n## By the numbers\n\nThese are factual claims about piia-engram itself, refreshed each minor release.\n\n| | v3.26.0 (2026-05-23) |\n|---|---|\n| Supported AI tools | **13** (4 verified + 7 expected-to-work + OpenClaw + ChatGPT fallback) |\n| MCP tools exposed | **60** (12 Tier-1 default, 48 opt-in via `ENGRAM_TOOLS=all`) |\n| Knowledge types | **3** (lessons, decisions, playbooks) |\n| Tests passing | **768** (unit + integration) |\n| Code coverage | **96%** total; mcp_server 99%, setup_wizard 93%, storage 100%, core 95% |\n| Lines in `core.py` | **1097** (down from 4277 pre-v3.14.1 — see [architecture.md](docs\u002Farchitecture.md)) |\n| PBKDF2 iterations | **600,000** (OWASP 2023+ floor; legacy 100k still decrypts) |\n| Encryption | AES-256-GCM, per-value random salt + nonce |\n| Cold-start time | \u003C 100 ms typical (local JSON, no network) |\n| Network calls from core | **0** by default — except optional `read_web_content` and opt-in anonymous usage statistics (Phase 2: local + optional remote — [details](docs\u002Ftelemetry_roadmap.md)) |\n| External AI evaluations | 4 independent AIs evaluated the telemetry design; 3 earlier evaluations on architecture (see [`docs\u002F`](docs\u002F)) |\n\n## Built With\n\npiia-engram is a human-directed, AI-assisted open-source project.\n\n| Contributor | Role |\n|---|---|\n| [@Patdolitse](https:\u002F\u002Fgithub.com\u002FPatdolitse) | Creator, product direction, strategy, ownership |\n| Claude Code | Architecture, task planning, code review assistance |\n| Codex | Implementation, testing, documentation assistance |\n\n## FAQ\n\n**What MCP server lets me share memory between Claude Code and Cursor?**\npiia-engram. Install with `pip install piia-engram && engram setup`, and both tools read the same identity, preferences, and lessons from `~\u002F.engram\u002F`. No cloud, no sync service — they both read local JSON files through MCP.\n\n**What is piia-engram?**\npiia-engram is a persistent memory layer for AI tools. It stores your identity, preferences, code standards, lessons learned, and key decisions as local JSON files on your machine. Every MCP-compatible AI tool (Claude Code, Codex, Cursor, Windsurf, Claude Desktop) reads the same context, so new chats, tool updates, and tool switches never erase who you are.\n\n**How is piia-engram different from the official MCP memory server?**\nThe official `@modelcontextprotocol\u002Fserver-memory` stores a generic knowledge graph of entities and relations. piia-engram is specialized for **developer identity**: it has structured fields for your profile, code standards, quality bar, lessons learned, and key decisions — plus 60 tools for knowledge lifecycle management (search, review, merge, inherit across projects). If you need general-purpose entity memory, use the official server. If you want every AI tool to know your coding preferences and past mistakes, use piia-engram.\n\n**How is piia-engram different from agent memory tools like Mem0, Zep, or Letta?**\nThose tools store task context and session history for AI agents — what happened during a workflow. piia-engram stores who *you* are as a person — your identity, preferences, hard-won lessons, and key decisions. It's a different layer: identity persists across tools, sessions, and projects, while task memory is scoped to a single agent run. Your data is local JSON files you own and can edit directly.\n\n**Why not just use AGENTS.md \u002F CLAUDE.md \u002F .cursorrules?**\nThose config files are great for **repo-specific** rules (build steps, coding conventions). piia-engram is for **you** — your preferences, lessons, and decisions that follow you across every repo and every AI tool. They complement each other: use AGENTS.md for the project, piia-engram for the person. See the full comparison in [docs\u002Fcomparison.md](docs\u002Fcomparison.md).\n\n**Can I use piia-engram with multiple AI tools at once?**\nYes. That's the primary use case. piia-engram uses local file storage (`~\u002F.engram\u002F`) with atomic writes and file locking. Claude Code, Cursor, Codex, and any other MCP client can connect simultaneously. A lesson recorded in Claude Code is immediately available in Cursor.\n\n**Which AI tools does piia-engram support?**\nAny MCP-compatible tool: Claude Code, OpenAI Codex, Cursor, Claude Desktop, Windsurf, GitHub Copilot, Cline, Roo Code, Amazon Q, Augment, Zed, and more. For tools without MCP support (ChatGPT, Gemini, Kimi), export a Markdown identity card with `get_identity_card` and paste it in.\n\n**Where is my data stored?**\nAll data lives in `~\u002F.engram\u002F` on your local machine as plain JSON and Markdown files. No cloud, no account, no subscription. You can open, edit, back up, or migrate the files yourself. Optional AES-256-GCM encryption is available via `pip install piia-engram[secure]`.\n\n**How do I install piia-engram?**\n```bash\npip install piia-engram\nengram setup\n```\nThe setup wizard detects your AI tools and configures MCP automatically. Restart your AI tool after setup. The AI will call `get_user_context` at the start of each session.\n\n**After upgrading, my AI tool shows \"MCP server disconnected\". How do I fix it?**\nRun `engram doctor --fix` in a terminal, then restart your AI tool. This command scans all known MCP config files, removes outdated server entries, and repairs broken paths in one step.\n\n**Does piia-engram send data to the cloud?**\nNo. All core tools make zero network requests. Optional anonymous usage statistics (tool call counts, never content) can be enabled during setup but are **off by default**. You can inspect the payload with `engram telemetry preview` and disable anytime with `engram telemetry off`.\n\n**How many MCP tools does piia-engram provide?**\n60 tools: 12 Tier-1 Core tools loaded by default (identity, knowledge, playbooks, project context, session recovery) plus 48 Tier-2 Advanced tools for tools registry, knowledge management, review, import\u002Fexport, and audit logging. Enable all with `ENGRAM_TOOLS=all`.\n\n**Is piia-engram free?**\nYes. Free and open source under the Apache 2.0 license. No subscription, no cloud tiers, no vendor lock-in.\n\n## Limitations\n\npiia-engram is functional and actively used, but some things it intentionally does not do yet:\n\n| Area | Current State | Planned |\n|---|---|---|\n| **File safety** | Atomic JSON writes with a shared portalocker file lock | Broader stress testing |\n| **Access control** | `restricted_fields` filters profile in `get_user_context`, `get_profile` (default safe=true), `get_identity_card`, and resource endpoints | Per-caller ACL blocked by MCP caller identity |\n| **Encryption** | Optional field-level AES-256-GCM encryption via `ENGRAM_SECRET` env var. Install `pip install piia-engram[secure]`. | Full-disk encryption for all files (v4.0) |\n| **Audit logging** | Optional access audit log via `ENGRAM_AUDIT=1` env var. Logs to `~\u002F.engram\u002Faudit.log`. | Per-caller audit (blocked by MCP spec) |\n| **Caller identity** | MCP protocol doesn't pass tool identity | Blocked by MCP spec |\n| **Concurrent writes** | Protected by file lock + atomic replace for piia-engram JSON writes | Network-filesystem edge cases not guaranteed |\n\n**What this means in practice:**\n- Don't store passwords, API keys, or client PII in piia-engram\n- Any process with read access to `~\u002F.engram\u002F` can read your data\n- `restricted_fields` reduces what piia-engram emits in cold-start context, but it is not encryption or a true ACL\n\nThis is not a warning to avoid piia-engram — it's an honest description of what it is: a local memory layer for personal AI context. For personal use, it works well today.\n\n## Security Configuration\n\n### Field-level encryption (optional)\n\nEncrypt sensitive profile fields (email, phone, location, etc.) at rest:\n\n```bash\npip install piia-engram[secure]\nexport ENGRAM_SECRET=\"your-strong-passphrase\"\n```\n\nEncrypted fields are stored as `enc:v1:...` in JSON files. Without `ENGRAM_SECRET`, piia-engram works normally with plaintext (backward compatible).\n\n### Audit logging (optional)\n\nTrack all read\u002Fwrite operations:\n\n```bash\nexport ENGRAM_AUDIT=1\n```\n\nLogs are written to `~\u002F.engram\u002Faudit.log` in JSON-lines format. Query with `get_audit_log` tool or `grep`.\n\n## CLI Commands\n\n```bash\nengram setup            # Interactive install wizard\npiia-engram doctor           # Check config health (all AI tools)\npiia-engram doctor --fix     # Auto-repair any issues found\npiia-engram stats            # Show project growth metrics (GitHub + PyPI)\npiia-engram stats --log      # Append stats snapshot to local log\nengram telemetry        # Manage anonymous usage statistics\nengram privacy          # Show what data piia-engram stores and where\n```\n\n## Contributing\n\nContributions, issues, and feedback are welcome.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Chinese readers can also use [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md).\n\n## License\n\n[Apache 2.0](LICENSE). piia-engram is free software. Your memory belongs to you.\n","piia-engram 是一个用于在不同AI工具间保持用户身份和偏好的持久记忆解决方案。它通过Model Context Protocol (MCP) 实现跨工具的记忆共享，支持Claude Code、Codex、Cursor等MCP兼容工具。其核心功能是将用户的偏好、标准和经验以本地JSON文件的形式存储，并在切换工具或开始新的会话时自动应用这些信息，从而避免了重复设置的麻烦。采用Python编写，遵循本地优先的原则，无需云服务或账户注册，确保数据完全由用户控制。适用于需要频繁使用多种AI开发工具且希望保持一致上下文环境的开发者或团队，能够显著提高工作效率并减少因工具切换导致的信息丢失问题。",2,"2026-06-11 03:56:46","CREATED_QUERY"]