patdolitse/piia-engram/engram

Engram

Engram is a local-first personal AI identity and memory layer exposed over MCP. It lets MCP-compatible coding tools (Claude Code, Codex, Cursor, and other MCP clients) start from the same user-approved understanding of who the user is, what they've decided, and what they've learned — without a cloud account and without hidden memory the user cannot inspect.

This skill tells you when to reach for Engram and which existing MCP tools to use. It does not add new behavior; it routes to the Engram MCP server.

When to use this skill

Reach for Engram when the user's request implies continuity, recall, or durable memory rather than a one-off task:

When the request is a normal coding task with no continuity or memory angle, do not invoke Engram — just do the task.

How to use it (routing, not magic)

1. Start of a continued session — call get_resume_brief to recover the last

thread of work. For identity and preferences on a fresh project, call get_user_context.

1. During work — when the user asks what was decided or learned, call

search_knowledge (topic known) or get_relevant_knowledge (let Engram pick what's relevant). Normal read/search tools provide session context; export surfaces such as get_identity_card are owner-gated and can write local files.

1. Capturing durable knowledge — the user, not the AI, owns what becomes

permanent. When the user says to remember something, propose it and write it with add_lesson / add_decision / add_playbook. These are user-approved writes, not automatic background memory.

1. End of session — call wrap_up_session to checkpoint context so the next

tool (or the next session) can resume.

Some MCP clients also run session hooks that capture context automatically; that context lands in the user-visible daily log and the staging tier, where it is inspectable and is not silently promoted to verified/trusted knowledge.

The full read/write tool map is in references/tools.md. Privacy, ownership, and storage boundaries are in references/privacy.md.

Honest boundaries

• Engram suggests; the user decides. AI-suggested knowledge is **staged

for review**, not silently promoted to verified/trusted memory; everything written lands in the user's local store where it can be inspected.

• Storage is local JSON the user owns. There is no cloud account and no

vendor lock-in. Engram sends one anonymous usage ping a day (random install ID, version, OS, Python version, AI client name, date); turn it off with engram telemetry off, ENGRAM_TELEMETRY=0 or DO_NOT_TRACK=1. Detailed usage statistics stay off unless the user turns them on; if enabled they write a local log only, and any remote sending is a separate explicit opt-in.

• Knowledge moves through a staging → verified path so unreviewed entries do

not silently become trusted facts.

• Do not claim capabilities Engram does not have. Use only the tool names in

references/tools.md; do not invent tools.

MCP server

Engram runs as an MCP server via the piia-engram-mcp command. Configure your MCP client to launch it (the Cursor plugin skeleton under .cursor-plugin/ shows one such wiring). By default the server exposes a Tier-1 core tool set; the full set is available with ENGRAM_TOOLS=all.