Piia Engram

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.

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?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ