Piia Engram — Claude Code MCP server: one profile for your agents
A local identity layer that lets several coding agents share your preferences, past decisions and project context. No cloud account involved.
claude mcp add --env ENGRAM_MCP_STARTUP_SYNC=<ENGRAM_MCP_STARTUP_SYNC> --env ENGRAM_TOOLS=<ENGRAM_TOOLS> --env PYTHONIOENCODING=<PYTHONIOENCODING> --transport stdio piia-engram -- uvx piia-engramWhat Piia Engram does
Piia Engram keeps your working preferences, quality bar, lessons from earlier tasks and project context as JSON and Markdown files under ~/.engram/. Claude, Codex, Cursor and Windsurf all read the same store, so none of them has to ask again which framework you use or how you like your tests written.
The AI proposes entries; you decide what sticks. Anything risky — credentials, shell commands, MCP config, permission rules — sits in a queue until you approve it, while low and medium writes land automatically and stay reversible. Setting ENGRAM_APPROVAL=strict makes every write wait for you. Run engram preview --html to see the exact payload an agent would get, including what governance held back.
Setup starts with pip install piia-engram && engram setup. The wizard detects your installed tools, lists the config files it plans to touch and backs each one up before writing. Python 3.10 or newer is required. Decline at the confirmation step and nothing on disk changes.
What it helps with
- carry one working profile across Claude and Codex
- inspect what an agent will receive before a task starts
- record a post-incident lesson so the agent applies it later
- hold credential and shell-command writes until you approve them
- point several editors at a single local context source
Example prompts for the agent
- Refactor the auth module and load my Engram profile first
- Show me which knowledge about me piia-engram is exposing
- Save this decision to Engram: keep auth middleware out of business logic
How to install Piia Engram
Platform CLI
claude mcp add --env ENGRAM_MCP_STARTUP_SYNC=<ENGRAM_MCP_STARTUP_SYNC> --env ENGRAM_TOOLS=<ENGRAM_TOOLS> --env PYTHONIOENCODING=<PYTHONIOENCODING> --transport stdio piia-engram -- uvx piia-engramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from piia-engram <command>
Platform CLI
codex mcp add piia-engram --env ENGRAM_MCP_STARTUP_SYNC=<ENGRAM_MCP_STARTUP_SYNC> --env ENGRAM_TOOLS=<ENGRAM_TOOLS> --env PYTHONIOENCODING=<PYTHONIOENCODING> -- uvx piia-engramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from piia-engram <command>
Config file
{
"mcpServers": {
"piia-engram": {
"command": "uvx",
"args": [
"piia-engram"
],
"env": {
"ENGRAM_MCP_STARTUP_SYNC": "<ENGRAM_MCP_STARTUP_SYNC>",
"ENGRAM_TOOLS": "<ENGRAM_TOOLS>",
"PYTHONIOENCODING": "<PYTHONIOENCODING>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from piia-engram <command>
Config file
{
"servers": {
"piia-engram": {
"type": "stdio",
"command": "uvx",
"args": [
"piia-engram"
],
"env": {
"ENGRAM_MCP_STARTUP_SYNC": "<ENGRAM_MCP_STARTUP_SYNC>",
"ENGRAM_TOOLS": "<ENGRAM_TOOLS>",
"PYTHONIOENCODING": "<PYTHONIOENCODING>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from piia-engram <command>
Platform CLI
gemini mcp add -e ENGRAM_MCP_STARTUP_SYNC=<ENGRAM_MCP_STARTUP_SYNC> -e ENGRAM_TOOLS=<ENGRAM_TOOLS> -e PYTHONIOENCODING=<PYTHONIOENCODING> piia-engram uvx piia-engramReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from piia-engram <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Piia Engram
How do I install Piia Engram in Claude Code?
Run pip install piia-engram && engram setup, then claude mcp add piia-engram -- uvx piia-engram. Restart Claude afterwards.
What does Piia Engram do?
It maintains a local set of facts about you and your projects that several MCP-compatible agents can read. The files stay on your machine and no cloud account is needed.
How is it different from Claude's built-in memory?
Built-in memory belongs to one tool or workspace. Engram sits above them, so the same files are available in Codex and Cursor too.
