Piia Engram
A user-owned local identity and long-term knowledge layer shared across AI coding tools.
- Source repo
- Patdolitse/piia-engram
- Stars
- ★ 166
- Last updated
- 12d ago
- License
- AGPL-3.0
- Primary language
- Python
- FA score
- 77/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude CodeChatGPT (Partial support)
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer alternating among Claude Code, Codex, and Cursor who wants every client to read the same coding preferences and lessons.
- Not a fit if
- Teams requiring encryption of every local memory file
- Organizations requiring cryptographically authenticated caller isolation
- Users seeking task-session history rather than personal identity knowledge
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-08latest release v4.27.0 (2026-11-01)
- Source review
- 77/100 · Good
What does this agent do, and when should you use it?
Piia Engram is a local-first AI work identity layer for developers, not a general agent session-memory database. It stores identity, preferences, quality standards, project snapshots, lessons, decisions, and operational playbooks as JSON and Markdown under ~/.engram/. A Python CLI and MCP stdio server expose retrieval, writeback, review, import/export, and session-recovery operations to clients such as Claude Code, Codex, and Cursor; ChatGPT, Gemini, and Kimi can use an exported Markdown identity card instead. Identity and knowledge operations make no network calls by default, while hybrid search, remote SSE deployment, encryption, governance, and telemetry are optional. It is a strong fit for developers who move between coding assistants and want inspectable, portable context, provided they accept the documented plaintext defaults and caller-identity limitations.
After installation, engram setup detects the Python environment and supported AI tools, asks where to keep the store, and—after confirmation—backs up and updates MCP configuration files. MCP clients can call get_user_context to load approved identity and knowledge, retrieve lessons, decisions, and playbooks through search_knowledge, get_relevant_knowledge, or get_recall, and write new material through add_lesson, add_decision, add_playbook, or the unified memory_store endpoint. save_project_snapshot, get_recent_context, and get_resume_brief support project and cross-session continuity; wrap_up_session records session outcomes and can create reviewable playbook drafts when it detects a multi-step workflow. High-risk material waits for review, low- and medium-risk writes remain auditable and reversible, and ENGRAM_APPROVAL=strict can gate every write. engram preview --as automation shows what a caller would receive, engram doctor diagnoses the installation, and export_engram, import_engram, and get_identity_card handle full backups, preview-first imports, and Markdown output for non-MCP tools. Search is keyword-based by default; installing the vector extra and setting ENGRAM_SEARCH=hybrid adds FTS5 plus semantic retrieval, including cross-language recall.
- A developer alternating among Claude Code, Codex, and Cursor who wants every client to read the same coding preferences and lessons.
- An engineer opening many fresh chats who wants
get_user_contextorget_resume_briefto reduce repeated onboarding. - A system architect preserving decisions, rejected alternatives, and rationale for retrieval across later projects.
- A team repeating release or deployment procedures that wants sessions converted into reviewable playbook drafts with recorded outcomes.
- A privacy-conscious individual who wants memory in inspectable, editable, backup-friendly local files.
- A user bringing the same work identity into ChatGPT, Gemini, or Kimi through an exported Markdown card when MCP is unavailable.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install piia-engrampip install "piia-engram[vector]"
- Config files
~/.codex/mcp.json- Runtime
- Python 3.10+
How do you install or deploy this agent?
Python 3.10+ is required. Install the package and run its interactive setup:
pip install piia-engram
engram setupThe wizard lists the client configuration files it intends to modify and writes the MCP connection only after confirmation, backing up each external file first. For CI or another non-interactive environment, apply the external configuration directly:
engram setup --apply-external-configRestart the configured AI client and verify the installation:
engram doctorOptional semantic vector retrieval requires the extra package:
pip install "piia-engram[vector]"Then set ENGRAM_SEARCH=hybrid in the MCP environment. The default identity and knowledge path requires neither a network connection nor an API key.
How do you use this agent?
For Codex, add this to ~/.codex/mcp.json:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"]
}
}
}Claude Code can register the stdio MCP server directly:
claude mcp add piia-engram -- piia-engram-mcpAfter restarting the client, call get_user_context to obtain approved identity and knowledge. During work, use search_knowledge for relevant lessons and decisions, write through memory_store or add_lesson, add_decision, and add_playbook, then call wrap_up_session when finishing. Preview the exact automation-facing context and check continuity from the terminal:
engram preview --as automation
engram continuityTo expose the advanced tool surface, add the environment setting to the MCP configuration:
{
"mcpServers": {
"piia-engram": {
"command": "python",
"args": ["-m", "piia_engram.mcp_server"],
"env": {
"ENGRAM_TOOLS": "all"
}
}
}
}For a client without MCP support, use get_identity_card and paste the generated Markdown into the conversation; that fallback is not automatic synchronization.
What are this agent's strengths and limitations?
- One local store serves multiple MCP coding clients, reducing dependence on any single product's native memory.
- JSON and Markdown records are directly inspectable, editable, portable, and backed by a Memory Lens preview of caller-visible context.
- Lessons, decisions, and playbooks have structured review, history, relation, merge, and cross-project inheritance workflows.
- Identity and knowledge operations make zero network calls by default; remote telemetry and feedback require separate opt-in.
- The CLI includes health checks, configuration repair, backup-before-write setup, and dry-run import planning.
- It supports MCP over stdio, a documented self-hosted SSE mode, and a Markdown fallback for clients without MCP.
- Local JSON and Markdown are plaintext by default; AES-256-GCM covers supported profile fields rather than the entire store.
- Any process with read access to
~/.engram/can read the data, andrestricted_fieldsis not a true ACL. - MCP does not provide reliable tool identity, so governance relies on environment variables rather than cryptographic authentication.
- Client evidence varies: Claude Code and Codex have a partial cross-tool proof, Cursor has a read/search evidence path, and several clients are only expected to work.
- Hybrid search adds a vector dependency, while remote operation requires a token, HTTPS reverse proxy, and CORS configuration.
- The supplied documentation disagrees on tool counts: some sections say 19 core or 59 total, while the enumerated table and FAQ say 18 core plus 40 advanced.
How does this agent compare with similar options?
Compared with Claude Memory, Piia Engram keeps its records in user-controlled local files and targets multiple MCP tools instead of the Claude ecosystem alone. Compared with CLAUDE.md or .cursorrules, it preserves personal preferences, lessons, and decisions across repositories; repository rule files remain the better place for project-specific build steps and conventions. Mem0, Zep, and Letta focus on task or session memory for agents, whereas Piia Engram focuses on the person behind those tasks and their enduring work standards. The official @modelcontextprotocol/server-memory provides a generic entity-relation knowledge graph, while Piia Engram adds structures specifically for developer identity, quality standards, lessons, decisions, and governed review.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Piia Engram This agent | 77 · Good | CLIFree | ★ 166 | 12d ago | Python | Codex · Claude Code |
| Remnic Agent Memory | 73 · Some gaps | CLIFree + model costs | ★ 235 | today | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| Mnemo Cortex | 75 · Good | Self-hosted serviceFree | ★ 161 | 1d ago | Python | Codex · Claude Code · Claude.ai |
| mex Project Memory | 84 · Good | CLIFree | ★ 1.8k | 2d ago | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The documents describe local JSON/Markdown storage, plaintext defaults, the daily anonymous usage ping and opt-outs; the security and telemetry notes specify payloads, destination, optional web reads and local audit logs. Setup previews touched configs, asks for confirmation and backs them up. Low/medium-risk knowledge is nevertheless auto-verified, the default ping still sends data, and field encryption is optional, so these controls do not merit full marks.
The CI configuration shows Python-version coverage, tests for optional dependencies and dependency-audit steps; CLI guidance also explains transport and migration failures. However, the README skill says durable knowledge is user-reviewed, while the quickstart says low/medium-risk items are immediately auto-verified. That inconsistency lowers self-consistency. Static evidence cannot confirm actual test results.
The product targets multiple MCP coding tools and cross-session memory, separates core and advanced tools, offers identity-card export for non-MCP tools, and labels client evidence levels. Skill triggers are concrete and exclude ordinary coding tasks. Some integrations are only expected or still awaiting evidence, and the main workflow assumes a local Python/MCP environment, so environment fit is not fully established.
Documentation is organized across quickstart, integrations, privacy, governance and operations, with detailed installation, FAQ, limitations and bilingual guidance. The license file matches package metadata. A version and release checks are shown, but the supplied material does not establish clear named maintenance responsibility or provide a changelog, so those scores are conservative.
The product makes editable identity, lessons and decisions available across tools, with concrete recall, resume and export workflows. Benefits depend on clients invoking the tools and on local setup; optional tools and vector search add configuration and dependency costs, so cost-benefit is moderate.
The README gives detailed references for capability levels, telemetry, encryption, network calls and validation boundaries; CI lists tests and claim-sync gates. Several claims remain repository assertions, and this packet does not include corresponding run artifacts or all relevant source for independent cross-checking, so corroboration is not full.
- The default daily ping sends an anonymous install ID, version, OS, Python version, client name and date; review its status and payload preview if this is unsuitable.
- Local memory is plaintext by default. Field-level encryption requires an optional install and key configuration, and does not encrypt the whole store.
- Automatic verification of low/medium-risk writes does not fully match the skill's user-decision description; confirm the active approval policy before relying on review semantics.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
English Features - Hook queue body protection. When store encryption is enabled, hook queue events are stored in an authenticated encrypted envelope. Plaintext publication and encryption enablement share a root-local policy gate, and recovery diagnostics stay read-only. Existing plaintext queues remain readable. Downstream archives, digests and other generated outputs are not covered. See [Hook queue protection](https://github.com/Patdolitse/piia-engram/blob/main/docs/hook-queue-protection.md). …View on GitHub ↗ -
Release notes excerpt
English Features - Isolated store contract v1 lets callers check compatibility with CONTRACT_VERSION and require_contract("1"). - Both isolated modes support atomic admission that supersedes a matching item. Family, subject and decision point must match; an older version cannot be restored while its replacement is active. - Recall receipts include a deterministic result_sha256 for verifying the returned result. Existing receipts remain readable. Fixes …View on GitHub ↗ -
Release notes excerpt
English More reliable isolated store retries, verifiable recall receipts, and logical lifecycle times for replay experience. - Both isolated store modes accept optional event keys for idempotent retries and refuse conflicting reuse. Independent events can retain identical templates; unkeyed admission keeps its existing behavior. - Recall receipts include a snapshot ID, ordered item IDs, content hashes, and a query digest and term count. verify_recall_receipt checks integrity and reports retirement, veto, changed content or missing items without returning their bodies. …View on GitHub ↗
FAQ
Does it require a paid model or cloud account?
Is the local data encrypted by default?
piia-engram[secure] and setting ENGRAM_SECRET enables AES-256-GCM for supported profile fields, not full-store encryption.Will setup silently change my Codex or Cursor configuration?
engram setup displays the target files and waits for confirmation, creating backups before writing; declining leaves them unchanged. engram setup --apply-external-config intentionally skips that prompt.What should I do if MCP disconnects after an upgrade?
piia-engram doctor --fix and restart the affected AI client. The command checks known MCP configurations and repairs stale entries or broken paths.Can ChatGPT connect directly to the same live memory?
get_identity_card and paste it into the chat. It is not the same live local connection offered to MCP clients.Is Piia Engram open source?
Is Piia Engram safe to use?
Is Piia Engram still maintained?
Who makes Piia Engram?
Thanks — we use this to improve the page.