皮亚身份层

Remote Deployment

Run piia-engram on your own server and connect from anywhere.

Server Setup

```bash

Install with remote support

pip install piia-engram[remote]

Quick Start (30 seconds)

pip install piia-engram
engram setup

The setup wizard will: 1. Detect your Python environment 2. Find and configure your AI tools (Claude Code, Cursor, Claude Desktop) 3. Walk you through seed knowledge (role, tech stack, language) 4. Smart-import rules from your existing CLAUDE.md / .cursorrules files 5. Show your privacy preferences (cross-tool sync, anonymous statistics — both optional) 6. Preview your AI identity card — immediate proof of value

Restart your AI tool after setup. The first conversation will call get_user_context automatically — your AI already knows you.

<details> <summary><strong>Manual MCP configuration</strong></summary>

If you prefer to configure manually, add to your AI tool's MCP config:

{
  "mcpServers": {
    "piia-engram": {
      "command": "python",
      "args": ["/path/to/piia-engram/src/piia_engram/mcp_server.py"]
    }
  }
}

</details>

Client Config (Claude Code)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Client Config (Cursor)

{
  "mcpServers": {
    "piia-engram": {
      "url": "http://your-server:8767/sse",
      "headers": {
        "Authorization": "Bearer abc123..."
      }
    }
  }
}

Security notes: - Always use HTTPS in production, behind nginx or caddy with TLS. - The auth token protects your identity data. Keep it secret. - Default bind is 127.0.0.1 for localhost only. Use 0.0.0.0 only behind a reverse proxy. - Set ENGRAM_CORS_ORIGINS to restrict cross-origin access (e.g. https://your-domain.com). - Data stays on your server and never touches third-party clouds.

Security Configuration

Field-level encryption (optional)

Encrypt sensitive profile fields (email, phone, location, etc.) at rest:

pip install piia-engram[secure]
export ENGRAM_SECRET="your-strong-passphrase"

Encrypted fields are stored as enc:v1:... in JSON files. Without ENGRAM_SECRET, piia-engram works normally with plaintext (backward compatible).

Audit logging (optional)

Track all read/write operations:

export ENGRAM_AUDIT=1

Logs are written to ~/.engram/audit.log in JSON-lines format. Query with get_audit_log tool or grep.

CLI Commands

engram setup            # Interactive install wizard
piia-engram doctor           # Check config health (all AI tools)
piia-engram doctor --fix     # Auto-repair any issues found
piia-engram stats            # Show project growth metrics (GitHub + PyPI)
piia-engram stats --log      # Append stats snapshot to local log
engram telemetry        # Manage anonymous usage statistics
engram privacy          # Show what data piia-engram stores and where

Tier-1 Core (10 tools — daily workflow)

Comparison

📊 For the full side-by-side, including when to choose a competitor over piia-engram, see docs/comparison.md.

FAQ

What is piia-engram? piia-engram is a local-first AI identity layer — not session memory, not an agent framework. It stores who you are, how you work, what you've learned, and the decisions you've made — as local JSON files on your machine. Every MCP-compatible AI tool (Claude Code, Codex, Cursor) reads the same identity, so new chats, tool updates, and tool switches never erase your context.

How is piia-engram different from agent memory tools like Mem0, Zep, or Letta? Those tools store task context and session history for AI agents — what happened during a workflow. piia-engram stores who you are as a person — your identity, preferences, hard-won lessons, and key decisions. It's a different layer: identity persists across tools, sessions, and projects, while task memory is scoped to a single agent run. Your data is local JSON files you own and can edit directly.

Which AI tools does piia-engram support? piia-engram works with any MCP-compatible AI tool: Claude Code, OpenAI Codex, Cursor, Claude Desktop, and others. For tools without MCP support (ChatGPT, Gemini, Kimi), you can export a Markdown identity card and paste it in manually.

Why is the PyPI package called piia-engram if the product is just "piia-engram"? The project started as part of a larger personal-AI initiative called PIIA (Personal Intelligence Identity Asset) — piia-engram is the first and currently the only released tool in that line, so it kept the piia- prefix on PyPI. Day-to-day the product is just piia-engram — that's the CLI command (engram setup, piia-engram doctor), the import name (import piia_engram), and the MCP server name (engram). The piia- prefix only shows up at install time and may be retired in a future major version.

How do I install piia-engram?

pip install piia-engram
engram setup

After upgrading, my AI tool shows "MCP server disconnected". How do I fix it? Run piia-engram doctor --fix in a terminal, then restart your AI tool. This command scans all known MCP config files (Claude Code, Cursor, Claude Desktop), removes outdated server entries, and repairs broken paths in one step. piia-engram also runs this migration automatically the next time its server starts, so most users will never see this message.

Does piia-engram send data to the cloud? All identity and knowledge data is stored in ~/.engram/ on your local machine. Core identity and knowledge tools make no network requests. Anonymous usage statistics (tool call counts, knowledge totals, piia-engram version — never content, prompts, or file paths) can be optionally enabled during engram setup; they are off by default. You can inspect the exact payload with engram telemetry preview and disable anytime with engram telemetry off. The optional read_web_content tool makes outbound HTTP requests to a local Reader service (localhost:7890) which may in turn fetch external URLs — but only when explicitly invoked.

How many MCP tools does piia-engram provide? piia-engram exposes 43 MCP tools covering identity management, lessons learned, key decisions, project snapshots, bulk input, note ingestion, session insight extraction, weighted knowledge search, similarity discovery, merging, lifecycle review, digesting, reporting, linking, health checks, workflow shortcuts, and audit logging.

Is piia-engram free? Yes. piia-engram is free and open source under the Apache 2.0 license.