get_user_contextLABSCO SUMMARY
You can see exactly what it would send before it sends anything.
The claim every memory tool makes is that your data stays yours; this one ships the check. Memory Lens renders a read-only report of precisely what a caller would receive and what was withheld, with secrets shown redacted, so "local and inspectable" is something you verify rather than accept. The files under ~/.engram/ are plain JSON and Markdown for the same reason.
What it is
A local-first store of your working identity — preferences, quality bar, lessons, decisions and project context — that any MCP-compatible tool can read. The distinction it draws is deliberate: it is not an agent memory database holding task history, it is the user-owned layer above whatever memory Claude Code, Codex, Cursor or Windsurf each keep for themselves.
What you get
- A session-start call that loads identity plus relevant knowledge, with a
token_budgetparameter so you control how much context it spends —get_user_context,get_recall - Three knowledge types — lessons, decisions and playbooks — written through one unified endpoint that routes by kind —
memory_store,add_lesson,add_decision,add_playbook - Search across all three with domain, tier and date filters, plus a project-relevant view —
search_knowledge,get_relevant_knowledge - Session recovery after a restart and a cross-tool resume brief —
get_recent_context,get_resume_brief,get_daily_log,wrap_up_session - Project snapshots saved and read back so a new session starts where the last one stopped —
save_project_snapshot,get_project_context - A Markdown identity card exported for tools that do not speak MCP at all, such as ChatGPT or Gemini —
get_identity_card - Memory Lens:
engram preview --htmlshows exactly what an AI caller would receive and what governance withheld — including a lesson containing a credential shown as[REDACTED]— before anything is sent - An advanced surface behind
ENGRAM_TOOLS=allcovering knowledge review and staging, merging and relations, graph exploration, import and export, caller trust management and the audit log —review_staging,merge_knowledge,explore_knowledge,manage_caller_trust,get_audit_log - A self-diagnosis tool for when the store misbehaves —
doctor
Requirements
Python 3.10 or higher: pip install piia-engram && engram setup. The wizard detects Claude Code, Cursor, Codex and Claude Desktop, lists the exact config files it will touch, backs each one up, and writes only after a confirm — decline and nothing changes. Identity and knowledge live under ~/.engram/ as plain JSON and Markdown. High-risk items — credentials, shell commands, MCP config, permission rules — wait for your review; low and medium writes are absorbed automatically but stay auditable and reversible, and ENGRAM_APPROVAL=strict gates every write. ENGRAM_TOOLS=all unlocks the advanced surface; ENGRAM_MCP_STARTUP_SYNC controls whether startup reconciliation runs in the background, eagerly, or not at all. Identity and knowledge tools make no network calls by default — the exception is read_web_content, which fetches a URL you supply. Licensed AGPL v3.
Setup effort
One command — pip install piia-engram && engram setup
USE CASES
01
Starting every tool from the same understanding of you
Load identity and approved knowledge at session start, with a token budget so a large store does not eat the context window.
02
Moving mid-task from one coding tool to another
Build a resume brief and read the project snapshot in the second tool rather than re-explaining the state.
03
Making a hard-won lesson stick
Record it as a lesson or decision with reasoning, and let relevance retrieval surface it the next time the same area comes up.
04
Checking what an AI caller can actually see
Run the HTML preview to read the exposed-versus-withheld report, with any credential in a lesson shown redacted.
05
Reviewing what the AI proposed before it counts
Work the staging queue — list pending items, batch-decide, and confirm the ones worth keeping.
57 tools
Listed in project docs. Your client may show a different list.
wrap_up_sessionmemory_storeadd_lessonadd_decisionadd_playbooksearch_knowledgeget_relevant_knowledgeget_recallget_identity_cardupdate_identityget_project_contextsave_project_snapshotget_recent_contextget_daily_logget_resume_briefdoctorregister_toolfind_toollist_toolssave_agent_contextlist_agent_sessionsrefresh_quick_contextget_identity_facetsuser_portraitpreview_context_governanceget_playbooksmanage_playbookplaybook_executionget_lessonsget_decisionsget_knowledge_inheritancelist_projectsextract_session_insightsingest_notesupdate_knowledgearchive_knowledgeconfirm_knowledgeonboard_repoonboard_acceptcheck_anchorsmerge_knowledgemanage_relationexplore_knowledgeget_knowledge_overviewget_stale_knowledgereview_stagingexport_knowledge_reportrequest_outline_reviewexport_engramimport_engramread_web_contentget_audit_logstart_projectget_permission_profilemanage_caller_trustexport_feedback_reportBEFORE YOU INSTALL
What to know first
Tools you get
57 tools named in the project's documentation.
Requires
piia-engram-mcp on PATH
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install piia-engram && engram setupMCP Clients
Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"engram": {
"command": "piia-engram-mcp",
"args": [
"--transport",
"stdio"
]
}
}
}Cursor
CURSOR · JSON
{
"mcpServers": {
"piia-engram": {
"command": "piia-engram-mcp",
"args": [
"--transport",
"stdio"
]
}
}
}Claude Desktop, Cline, Windsurf, GitHub Copilot, Trae, Tencent Codebuddy
JSON
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": [
"-m",
"piia_engram.mcp_server"
]
}
}
}Claude Code — SSE
On your server, install with remote support:
CLAUDE CODE — SSE · TERMINAL
pip install piia-engram[remote]Generate an auth token: python -c "import secrets; print(secrets.token_urlsafe(32))"
Start the server in SSE mode with that token:
CLAUDE CODE — SSE · TERMINAL
ENGRAM_AUTH_TOKEN=<YOUR_ENGRAM_AUTH_TOKEN> python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767Add this to your client configuration:
CLAUDE CODE — SSE · JSON
{
"mcpServers": {
"piia-engram": {
"type": "sse",
"url": "http://<YOUR_SERVER>:8767/sse",
"headers": {
"Authorization": "Bearer <YOUR_TOKEN>"
}
}
}
}<YOUR_SERVER> is your server's host name. The README advises serving it over HTTPS behind nginx or caddy in production, and binding to 0.0.0.0 only behind a reverse proxy.
Cursor — SSE
On your server, install with remote support:
CURSOR — SSE · TERMINAL
pip install piia-engram[remote]Generate an auth token: python -c "import secrets; print(secrets.token_urlsafe(32))"
Start the server in SSE mode with that token:
CURSOR — SSE · TERMINAL
ENGRAM_AUTH_TOKEN=<YOUR_ENGRAM_AUTH_TOKEN> python -m piia_engram.mcp_server --transport sse --host 0.0.0.0 --port 8767Add this to your client configuration:
CURSOR — SSE · JSON
{
"mcpServers": {
"piia-engram": {
"url": "http://<YOUR_SERVER>:8767/sse",
"headers": {
"Authorization": "Bearer <YOUR_TOKEN>"
}
}
}
}<YOUR_SERVER> is your server's host name. The README advises serving it over HTTPS behind nginx or caddy in production, and binding to 0.0.0.0 only behind a reverse proxy.
