Piia Engram

by Patdolitse

170 539 downloads Not rated yet AGPL-3.0

GitHub Website

About

Persistent AI memory across tools — remember your preferences, code standards, and decisions across Claude Code, Cursor, Codex, and any MCP tool. Local-first, zero-cloud.

Details

License: AGPL-3.0

Explore

- Local files you own, no cloud account required
- AI-proposed knowledge reviewed by user before high-risk writes
- Portable identity across multiple MCP-compatible coding tools
- Memory Lens (engram preview --html) shows what AI callers receive
- Field-level optional AES-256-GCM encryption for sensitive profile fields
- 17 core MCP tools (loaded by default) + 40 advanced tools (opt-in)

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Piia Engram

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

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 context through startup or search tools. (full walkthrough ↓)

---

<details open>
<summary><strong>Claude Code</strong></summary>

engram setup 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: 17 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))

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

bash

pip install piia-engram[remote]

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

{
  "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.

`Codex`

MCP over stdio

`Cursor`

MCP over stdio

`Hermes`

MCP over stdio

`OpenClaw`

SOUL.md / MEMORY.md / USER.md import and export

`Windsurf`

MCP over stdio

`Cline`

MCP over stdio

`Augment`

MCP over stdio

`Zed`

MCP over stdio

`Trae`

MCP over stdio

`get_user_context`

**Startup** — Load identity + knowledge at session start (supports `token_budget` for context size control)

`wrap_up_session`

**Session end** — Save insights + sync at session end

`memory_store`

**Writeback** — Unified write endpoint: routes to add_lesson / add_decision / add_playbook by `kind`

`add_lesson`

Store a reusable lesson learned

`add_decision`

Record a key decision with reasoning

`add_playbook`

Record an operational playbook (multi-step procedure with trigger keywords)

`search_knowledge`

**Retrieval** — Search lessons, decisions, and playbooks (supports `filters_json` for domain/tier/date filtering)

`get_relevant_knowledge`

Find knowledge relevant to current project

`get_recall`

Return one structured identity + recent activity + relevant knowledge recall payload

`get_identity_card`

Owner-gated export: write and return a Markdown identity card for non-MCP tools

`update_identity`

Update profile, preferences, or quality standards

`get_project_context`

Read a saved project snapshot

`save_project_snapshot`

Persist project state for future sessions

`get_recent_context`

Recover lost session context after restart

`get_daily_log`

Read a human-friendly project timeline for a day

`get_resume_brief`

Build a cross-session/cross-tool resume brief

`doctor`

Run memory system self-diagnosis

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

</div>

---

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

Evidence levels follow the agent client validation runbook: L0 = untested, L1 = installed, L2 = read/search observed, L3 = static file bridge, L4 = cross-client continuity.

| 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 | L2 end-to-end verified (hermes-agent 0.15.2, 2026-06-03) |
| OpenClaw | SOUL.md / MEMORY.md / USER.md import and export | L3 static file-bridge evidence |
| 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 |

<details open>
<summary><strong>Claude Code</strong></summary>

piia-engram ships 57 MCP tools. By default, only the 17 Tier-1 Core tools are loaded to keep the AI's context clean. Core means "used in most sessions", not "read-only": some core tools write local memory or owner-gated export files, and the governance layer still gates those side effects. For the short operator view, see the MCP cheatsheet. To unlock all 57 tools, add ENGRAM_TOOLS=all to your MCP config: You can also expose composable capability modes such as knowledge management, governance, admin, or integrations; see the capability modes guide.

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

Startup sync: Engram reconciles memories/config snippets from local AI tools when an MCP server starts. By default this runs in the background so stdio clients can initialize quickly. Set ENGRAM_MCP_STARTUP_SYNC=eager to restore synchronous startup sync, or ENGRAM_MCP_STARTUP_SYNC=off to skip startup sync for latency-sensitive test arms. ENGRAM_EPHEMERAL=1 also skips startup sync and migration work in container/ephemeral clients.

| Tool | Purpose | |---|---| |get_user_context | Startup — Load identity + knowledge at session start (supports token_budgetfor context size control) | |wrap_up_session| Session end — Save insights + sync at session end | |memory_store | Writeback — Unified write endpoint: routes to add_lesson / add_decision / add_playbook by kind| |add_lesson| Store a reusable lesson learned | |add_decision| Record a key decision with reasoning | |add_playbook| Record an operational playbook (multi-step procedure with trigger keywords) | |search_knowledge | Retrieval — Search lessons, decisions, and playbooks (supports filters_jsonfor domain/tier/date filtering) | |get_relevant_knowledge| Find knowledge relevant to current project | |get_recall| Return one structured identity + recent activity + relevant knowledge recall payload | |get_identity_card| Owner-gated export: write and return a Markdown identity card for non-MCP tools | |update_identity| Update profile, preferences, or quality standards | |get_project_context| Read a saved project snapshot | |save_project_snapshot| Persist project state for future sessions | |get_recent_context| Recover lost session context after restart | |get_daily_log| Read a human-friendly project timeline for a day | |get_resume_brief| Build a cross-session/cross-tool resume brief | |doctor` | Run memory system self-diagnosis |

Advanced tools include optional local integrations, owner/admin surfaces, and maintenance helpers. Tools that export files, import whole stores, generate revie

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

McpServers

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

Local-first AI work identity you can see, edit, and override — portable across your MCP coding tools.

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

</div>

---

Trust model in four lines:

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"

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

Codex

Cursor

Hermes

OpenClaw

Windsurf

Cline

Augment

Zed

Trae

get_user_context

wrap_up_session

memory_store

add_lesson

add_decision

add_playbook

search_knowledge

get_relevant_knowledge

get_recall

get_identity_card

update_identity

get_project_context

save_project_snapshot

get_recent_context

get_daily_log

get_resume_brief

doctor

Claude Desktop / Cursor

McpServers

Local-first AI work identity you can see, edit, and override — portable across your MCP coding tools.

See It in Action

More like this

Aws Kb Retrieval Server

Time

Memory

Context 7

`Codex`

`Cursor`

`Hermes`

`OpenClaw`

`Windsurf`

`Cline`

`Augment`

`Zed`

`Trae`

`get_user_context`

`wrap_up_session`

`memory_store`

`add_lesson`

`add_decision`

`add_playbook`

`search_knowledge`

`get_relevant_knowledge`

`get_recall`

`get_identity_card`

`update_identity`

`get_project_context`

`save_project_snapshot`

`get_recent_context`

`get_daily_log`

`get_resume_brief`

`doctor`