piia-engram MCP Server

piia-engram

Local identity and memory for MCP-compatible coding tools.

AI suggests lessons and decisions. You approve what becomes durable.

Tell AI once how you work. piia-engram stores your identity, standards, lessons, decisions, and project context as local files you own. Claude Code, Codex, Cursor, Windsurf, and MCP-compatible tools can start from the same approved context. No cloud account, no vendor lock-in, no hidden memory you cannot inspect.

cross-tool memory | local-first | Claude Code | Codex | Cursor | Windsurf | MCP

ENGLISH | 中文

Listed in:

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 suggestions land in review before becoming verified memory.
• Documented boundaries: see Trust model, Privacy, and Security.

Want a safe public walkthrough? See the cross-tool continuity demo.

Install

pip install piia-engram && engram setup

The wizard auto-detects your AI tools — Claude Code, Cursor, Codex, Claude Desktop — in read-only mode, previews your identity card, and only writes external client config when you explicitly opt in. Restart your configured tool; the first conversation already knows you. (full walkthrough ↓)

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 context. 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?

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.

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:

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 in read-only mode without changing their external config files
4. Walk you through seed knowledge (role, tech stack, language)
5. Smart-import rules from your existing CLAUDE.md / .cursorrules files
6. In advanced mode (engram setup --advanced), show your optional privacy preferences (cross-tool sync, anonymous statistics)
7. Preview your AI identity card — immediate proof of value

If the MCP client is already configured, restart your AI tool after setup. If it is not configured yet, add the MCP entry manually or run the explicit opt-in command below. The first connected conversation will call get_user_context automatically — your AI already knows you.

To let Engram update Claude/Codex/Cursor/Zed MCP config files for you, run:

engram setup --apply-external-config

External config writes are explicit opt-in and create backups under the selected Engram data folder.

Check health anytime:

engram status        # redacted install + memory health summary
engram status --html # write a local redacted status page
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 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.

Configure for Your AI Tool

# Guided setup; external client configs stay read-only by default
engram setup
# Explicit opt-in if you want Engram to write the client config with backups
engram setup --apply-external-config
# Or manual:
claude mcp add piia-engram -- piia-engram-mcp

{
  "mcpServers": {
    "piia-engram": {
      "command": "piia-engram-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "command": "python",
  "args": ["-m", "piia_engram.mcp_server"]
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"]
    }
  }
}

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 already knows you
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..."

After setup, run engram doctor to verify everything is connected:

$ engram doctor

  Detected 3 AI tool(s):
    [ok] Claude Code — Engram configured
    [ok] Cursor — Engram configured
    [ok] Codex — Engram configured

  [ok] All configured tools look healthy.

  ── Functional Checks ──
    [ok] piia_engram.core importable
    [ok] Engram initialized (~/.engram)
    [ok] Identity loaded (role: Senior Backend Developer)
    [ok] quick_context.md ready (4096 bytes)
    [ok] MCP server: 16 tools registered

  -- Terminal encoding --

    [ok] stdout/stderr: utf-8 / utf-8
    [ok] PYTHONIOENCODING not set (stdout/stderr already UTF-8)
    [ok] Runtime encodings: preferred=UTF-8, filesystem=utf-8

  -- Config Integrity --

    [ok] MCP configs: 3/13 files found, 3 configured
    [ok] Instruction files: 3/4 found, 3 fresh
    [ok] Project rule files: 1 found
    [ok] Shared instructions: 1 found
    [ok] Claude hooks: 4/4 registered
    [ok] Report is metadata-only (hashes + counts; no rule bodies)

  -- Continuity --

    [--] No saved agent sessions yet
         Run an AI session, then wrap up or stop the tool to create one.
    [ok] Resume brief builds (2 section(s))

Upgrading

pip install --upgrade piia-engram

After 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:

piia-engram doctor        # show what's wrong
piia-engram doctor --fix  # auto-repair and fix in one step

Then restart the affected AI tool. The doctor command checks Claude Code, Cursor, Codex, Windsurf, Claude Desktop, and community-supported MCP config locations, removes outdated server entries, and prints a metadata-only config integrity summary.

Remote Deployment

Run piia-engram on your own server and connect from anywhere.

Server Setup

# Install with remote support
pip install piia-engram[remote]

# Generate an auth token
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Save the output, e.g. "abc123..."

# Start in SSE mode
ENGRAM_AUTH_TOKEN=abc123... python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767

Client Config (Claude Code)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Client Config (Cursor)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Security notes:

• Always use HTTPS in production, behind nginx or caddy with TLS.
• The auth token protects your identity data. Keep it secret.
• Default bind is 127.0.0.1 for localhost only. Use 0.0.0.0 only behind a reverse proxy.
• Set ENGRAM_CORS_ORIGINS to restrict cross-origin access (e.g. https://your-domain.com).
• Data stays on your server and never touches third-party clouds.

MCP Tools

piia-engram ships 80 MCP tools. By default, only the 16 Tier-1 Core tools are loaded to keep the AI's context clean. To unlock all 80 tools, add ENGRAM_TOOLS=all to your MCP config:

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["-m", "piia_engram.mcp_server"],
      "env": { "ENGRAM_TOOLS": "all" }
    }
  }
}

Tier-1 Core (16 tools — daily workflow)

Tier-2 Advanced (64 tools — knowledge management, review, governance, import/export)

Playbook Auto-Extraction

piia-engram can detect multi-step workflows you complete during a session and automatically draft structured playbooks — no manual recording required.

How It Works

1. 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.
2. 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.
3. Staging — The draft is saved to a staging area, never auto-promoted to verified. You review and confirm before it becomes a trusted playbook.
4. 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.

Design Philosophy: Engram Starts, You Confirm, AI Completes

Playbook 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.

Confidence Levels

Sensitive Info Redaction

Before any draft is stored, piia-engram automatically redacts:

• API keys and tokens (Bearer, sk-, ghp_, etc.)
• Absolute file paths (Windows and Unix)
• Email addresses
• Environment variable secrets

Kill Switch

Users can disable or re-enable playbook auto-extraction at any time:

• Disable: Tell your AI "关闭 playbook" / "stop playbook" / "disable playbook auto-extraction"
• Enable: Tell your AI "开启 playbook" / "start playbook" / "enable playbook auto-extraction"

The AI calls update_identity(field="preferences", ...) to toggle playbook_auto_extract. Default is enabled.

Manual Playbook Creation

You 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.

Data Layout

~/.engram/
|-- schema_version.json
|-- identity/
|   |-- profile.json
|   |-- preferences.json
|   |-- quality_standards.json
|   `-- trust_boundaries.json
|-- knowledge/
|   |-- lessons.json
|   |-- decisions.json
|   `-- domains.json
|-- playbooks/
|   |-- _index.json
|   `-- {playbook_id}.json
|-- tools/
|   `-- registry.json
|-- projects/
|   `-- {project_id}.json
|-- contexts/
|   `-- {tool_name}/
|       `-- {session_id}.md
|-- exports/
`-- compat/
    `-- openclaw/

Own & export your data

Everything lives in local JSON you own — inspect, edit, back up, or delete it directly. Three explicit export paths, each with a different boundary:

Exports are owner-gated when ENGRAM_GOVERNANCE=1 (see docs/governance.md). There is no cloud copy and no hidden memory: what you export is exactly what is on your disk.

Local data sovereignty. Backup and restore cover only the Engram directory — engram backup-plan prints a metadata-only list of what to copy before an upgrade (it reads no stored knowledge bodies and never reaches outside the Engram root), and restore is the explicit, manual step of copying that directory back. Engram never backs up, modifies, or deletes files in your project folders. See docs/runbooks/setup-upgrade-safety.md.

Supported Tools

Comparison

📊 For the full side-by-side, including when to choose a competitor over piia-engram, see docs/comparison.md.

By the numbers

These are factual claims about piia-engram itself, refreshed each minor release.

Built With

piia-engram is a human-directed, AI-assisted open-source project.

FAQ

What MCP server lets me share memory between Claude Code and Cursor? piia-engram. Install with pip install piia-engram && engram setup, and both tools read the same identity, preferences, and lessons from ~/.engram/. No cloud, no sync service — they both read local JSON files through MCP.

What is piia-engram? piia-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. Configured MCP-compatible coding tools (Claude Code, Codex, Cursor, Windsurf, Claude Desktop) can read the same approved context, so new chats and tool switches can start from the same user-owned memory.

How is piia-engram different from the official MCP memory server? The official @modelcontextprotocol/server-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 80 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 MCP-compatible coding tools to start from the same approved understanding of your preferences and past mistakes, use piia-engram.

How is piia-engram different from agent memory tools like Mem0, Zep, or Letta? Those 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.

Why not just use AGENTS.md / CLAUDE.md / .cursorrules? Those config files are great for repo-specific rules (build steps, coding conventions). piia-engram is for you — your preferences, lessons, and decisions that can follow you across repos and configured MCP-compatible tools. They complement each other: use AGENTS.md for the project, piia-engram for the person. See the full comparison in docs/comparison.md.

Can I use piia-engram with multiple AI tools at once? Yes. That's the primary use case. piia-engram uses local file storage (~/.engram/) 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.

Which AI tools does piia-engram support? Any 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.

Where is my data stored? All data lives in ~/.engram/ 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].

How do I install piia-engram?

pip install piia-engram
engram setup

The setup wizard detects your AI tools without changing their config files by default. To auto-configure MCP entries with backups, run engram setup --apply-external-config, then restart your AI tool. The AI will call get_user_context at the start of each session.

After upgrading, my AI tool shows "MCP server disconnected". How do I fix it? Run 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.

Does piia-engram send data to the cloud? Not by default. Identity and knowledge tools use local files, and telemetry is off by default. Optional anonymous usage statistics can be enabled as a local log; remote telemetry and weekly feedback reports require separate explicit opt-in and send counts only, never knowledge content. You can inspect the next payload with engram telemetry preview, disable anytime with engram telemetry off, and turn remote sending off with engram telemetry remote off. See PRIVACY.md for the full data flow diagram, what is and isn't collected, and your data rights.

How many MCP tools does piia-engram provide? Two tiers, designed so most users only see 16 tools:

Most users never need to enable Advanced tools — Core covers everyday use.

Is piia-engram free? Yes. Free and open source under the Apache 2.0 license. No subscription, no cloud tiers, no vendor lock-in.

Limitations

piia-engram is functional and actively used, but some things it intentionally does not do yet:

What this means in practice:

• Don't store passwords, API keys, or client PII in piia-engram
• Any process with read access to ~/.engram/ can read your data
• restricted_fields reduces what piia-engram emits in cold-start context, but it is not encryption or a true ACL

This 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.

Security Configuration

Field-level encryption (optional)

Encrypt sensitive profile fields (email, phone, location, etc.) at rest:

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

Encrypted fields are stored as enc:v2:... in JSON files; legacy enc:v1:... values still decrypt. Without ENGRAM_SECRET, piia-engram works normally with plaintext (backward compatible).

Audit logging (optional)

Track all read/write operations:

export ENGRAM_AUDIT=1

Logs are written to ~/.engram/audit.log in JSON-lines format. Query with get_audit_log tool or grep.

Agent governance (advanced, optional)

Enable per-caller trust levels and disclosure receipts:

export ENGRAM_GOVERNANCE=1
export ENGRAM_CLIENT_TYPE=claude_code

Governance is off by default. When enabled, known local coding agents are filtered to public/work knowledge, unknown callers fail closed to public-only, and owner-only exports/imports/grant changes require private-self. See docs/governance.md for the exact trust levels, gates, honest boundaries, and ledger commands.

CLI Commands

engram setup            # Interactive install wizard (external configs stay read-only)
engram setup --apply-external-config  # Auto-configure AI client MCP files with backups
piia-engram doctor           # Check config health (all AI tools)
piia-engram status           # Redacted install + memory health summary
piia-engram status --html    # Write a local redacted status page
piia-engram continuity       # Prove cross-tool handoff readiness (metadata only)
piia-engram management       # Show a metadata-only review/playbook management view
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram sessions         # List saved cross-tool agent sessions
piia-engram sessions show <id>  # Print one saved session
piia-engram review           # List staging knowledge awaiting review
piia-engram review show <id> # Inspect one review item
piia-engram review approve <id> --yes  # Promote a staging item
piia-engram review archive <id> --yes  # Archive a review item
piia-engram management action review approve <id> --yes --json  # Structured metadata-only action receipt
piia-engram management action playbook delete <id> --yes --json # Soft-delete a Playbook without body echo
piia-engram management action playbook_scope accept_project <id> --project . --yes --json # Resolve ambiguous Playbook scope
piia-engram management action playbook_scope accept_shared <id> --project ./app-a --project ./app-b --yes --json # Share one Playbook with selected projects
piia-engram repair-encoding  # Dry-run scan for garbled / mojibake text
piia-engram repair-encoding --apply  # Repair reversible cases with a backup
piia-engram backup-plan      # Metadata-only plan of what to copy before upgrading (local-only)
piia-engram export-agents-md # Export verified, non-sensitive knowledge as an AGENTS.md/CLAUDE.md block
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage anonymous usage statistics
engram privacy          # Show what data piia-engram stores and where

Contributing

Contributions, issues, and feedback are welcome.

See CONTRIBUTING.md.

License

Apache 2.0. piia-engram is free software. Your memory belongs to you.