Piia Engram

A user-owned local identity and long-term knowledge layer shared across AI coding tools.

Stars
★ 166
Last updated
12d ago
License
AGPL-3.0
Primary language
Python

At a glance

How it runs
CLIMCP serverSelf-hosted service
Works with
Universal · cross-platformCodex · Claude CodeChatGPT (Partial support)
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Python 3.10+An MCP-compatible client for direct integrationShell / CLILocal filesystemMCP Server
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.

  1. A developer alternating among Claude Code, Codex, and Cursor who wants every client to read the same coding preferences and lessons.
  2. An engineer opening many fresh chats who wants get_user_context or get_resume_brief to reduce repeated onboarding.
  3. A system architect preserving decisions, rejected alternatives, and rationale for retrieval across later projects.
  4. A team repeating release or deployment procedures that wants sessions converted into reviewable playbook drafts with recorded outcomes.
  5. A privacy-conscious individual who wants memory in inspectable, editable, backup-friendly local files.
  6. 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-engram
  • pip 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 setup

The 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-config

Restart the configured AI client and verify the installation:

engram doctor

Optional 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-mcp

After 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 continuity

To 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?

Pros
  • 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.
Limitations
  • 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, and restricted_fields is 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?

FollowAgents source review · FARS-2.1
Good
77/ 100 5-point scale 3.9 / 5
Trust 21/29
Reliability 8/14
Adaptability 15/18
Convention 16/18
Effectiveness 10/13
Verifiability 7/8
Why each dimension lost points
Trust21 / 29 · 3.6/5

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.

Reliability8 / 14 · 2.9/5

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.

Adaptability15 / 18 · 4.2/5

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.

Convention16 / 18 · 4.4/5

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.

Effectiveness10 / 13 · 3.8/5

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.

Verifiability7 / 8 · 4.4/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 2ab0cb645635 New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/piia-engram.svg)](https://followagents.com/en/agents/piia-engram)
<a href="https://followagents.com/en/agents/piia-engram"><img src="https://followagents.com/badge/piia-engram.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v4.27.0
    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 ↗
  2. v4.26.0
    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 ↗
  3. v4.25.0
    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?
No. It is AGPL-3.0 software with no subscription requirement for personal local use, and its identity and knowledge tools do not require a model API key.
Is the local data encrypted by default?
No. The default store is plaintext JSON and Markdown. Installing 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?
Run 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?
The documented ChatGPT path is a Markdown fallback: generate a card with 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?
Yes. The source code is on GitHub (Patdolitse/piia-engram) under the AGPL-3.0 licence. AGPL-3.0 is a copyleft licence that also covers network use: if you run a modified version as a service, you must offer its source to users.
Is Piia Engram safe to use?
FollowAgents' FARS review (Nov 08, 2026) scored Piia Engram 21/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is Piia Engram still maintained?
Yes. The latest commit on GitHub is from 2026-11-08, within the last 30 days. The latest release is v4.27.0 (2026-11-01).
Who makes Piia Engram?
Piia Engram is published on GitHub by the account Patdolitse. FollowAgents has not verified which person or company is behind that account.
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts