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:
| Signal |
Example phrasing |
Where to start |
| Resume work |
"continue from last session", "pick up where we left off" |
get_resume_brief |
| Recall a decision |
"what did we decide", "why did we choose X" |
search_knowledge, get_relevant_knowledge |
| Save a lesson |
"remember this", "save a lesson", "note this gotcha" |
add_lesson |
| Save a decision |
"record this decision", "we chose X because Y" |
add_decision |
| Save a playbook |
"save this as a playbook", "remember these steps" |
add_playbook |
| Search prior knowledge |
"have we seen this before", "search what we know about X" |
search_knowledge |
| Identity / preferences |
"who am I to you", "what are my preferences" |
get_user_context, get_identity_card |
| Export identity/context |
"export my identity card", "give me my context" |
get_identity_card |
| End of session |
wrapping up, summarizing what changed |
wrap_up_session |
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)
- 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.
- 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.
- 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.
- 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. Telemetry is off by default; if enabled it writes 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.
1---2name: engram3description: Local-first personal AI identity and memory layer for MCP-compatible coding tools (Claude Code, Codex, Cursor, and others). Use this skill when the user wants to continue from a previous session ("continue from last session", "pick up where we left off"), recall a past decision ("what did we decide", "what was our reasoning"), persist something durable ("remember this", "save a lesson", "save a decision", "save a playbook"), search prior knowledge ("search what we know about X", "have we hit this before"), export their identity or context ("export my identity card", "give me my context"), or maintain local-first cross-tool identity and memory that the user owns and approves. Engram stores user-approved lessons, decisions, playbooks, and project context as local JSON; the AI suggests, the user decides what becomes permanent.4license: AGPL-3.0-or-later5---67# Engram89Engram is a local-first personal AI identity and memory layer exposed over MCP.10It lets MCP-compatible coding tools (Claude Code, Codex, Cursor, and other MCP11clients) start from the same user-approved understanding of who the user is, what12they've decided, and what they've learned — without a cloud account and without13hidden memory the user cannot inspect.1415This skill tells you **when** to reach for Engram and **which existing MCP tools**16to use. It does not add new behavior; it routes to the Engram MCP server.1718## When to use this skill1920Reach for Engram when the user's request implies continuity, recall, or durable21memory rather than a one-off task:2223| Signal | Example phrasing | Where to start |24| --- | --- | --- |25| Resume work | "continue from last session", "pick up where we left off" | `get_resume_brief` |26| Recall a decision | "what did we decide", "why did we choose X" | `search_knowledge`, `get_relevant_knowledge` |27| Save a lesson | "remember this", "save a lesson", "note this gotcha" | `add_lesson` |28| Save a decision | "record this decision", "we chose X because Y" | `add_decision` |29| Save a playbook | "save this as a playbook", "remember these steps" | `add_playbook` |30| Search prior knowledge | "have we seen this before", "search what we know about X" | `search_knowledge` |31| Identity / preferences | "who am I to you", "what are my preferences" | `get_user_context`, `get_identity_card` |32| Export identity/context | "export my identity card", "give me my context" | `get_identity_card` |33| End of session | wrapping up, summarizing what changed | `wrap_up_session` |3435When the request is a normal coding task with no continuity or memory angle, do36**not** invoke Engram — just do the task.3738## How to use it (routing, not magic)39401. **Start of a continued session** — call `get_resume_brief` to recover the last41 thread of work. For identity and preferences on a fresh project, call42 `get_user_context`.432. **During work** — when the user asks what was decided or learned, call44 `search_knowledge` (topic known) or `get_relevant_knowledge` (let Engram pick45 what's relevant). Normal read/search tools provide session context; export46 surfaces such as `get_identity_card` are owner-gated and can write local47 files.483. **Capturing durable knowledge** — the user, not the AI, owns what becomes49 permanent. When the user says to remember something, propose it and write it50 with `add_lesson` / `add_decision` / `add_playbook`. These are51 user-approved writes, not automatic background memory.524. **End of session** — call `wrap_up_session` to checkpoint context so the next53 tool (or the next session) can resume.5455Some MCP clients also run session hooks that capture context automatically; that56context lands in the **user-visible daily log and the staging tier**, where it is57inspectable and is **not** silently promoted to verified/trusted knowledge.5859The full read/write tool map is in [references/tools.md](references/tools.md).60Privacy, ownership, and storage boundaries are in61[references/privacy.md](references/privacy.md).6263## Honest boundaries6465- Engram **suggests**; the user **decides**. AI-suggested knowledge is **staged66 for review**, not silently promoted to verified/trusted memory; everything67 written lands in the user's local store where it can be inspected.68- Storage is **local JSON the user owns**. There is no cloud account and no69 vendor lock-in. Telemetry is **off by default**; if enabled it writes a local70 log only, and any remote sending is a separate explicit opt-in.71- Knowledge moves through a **staging → verified** path so unreviewed entries do72 not silently become trusted facts.73- Do **not** claim capabilities Engram does not have. Use only the tool names in74 [references/tools.md](references/tools.md); do not invent tools.7576## MCP server7778Engram runs as an MCP server via the `piia-engram-mcp` command. Configure your79MCP client to launch it (the Cursor plugin skeleton under `.cursor-plugin/`80shows one such wiring). By default the server exposes a Tier-1 core tool set;81the full set is available with `ENGRAM_TOOLS=all`.
patdolitse