PMI · Personal Memory Infrastructure

My Memory, Any Agent. PMI is a long-term memory store that runs on your own machine. Give it PRDs, meeting notes, Notion pages, Linear tickets, GitHub PRs and Slack discussions: it keeps the original text and distills it into knowledge that always cites its source. Claude Code, Codex, Cursor and any other AI agent read and write the same memory through MCP (or the command line).

• Sourced: every memory carries a verbatim quote from the original text. Quotes are checked on write; a quote that does not match is rejected.

• Evolving: a newer decision automatically supersedes an older one, and the old one becomes history with a validity period. When new content conflicts with a conclusion you confirmed, PMI does not overwrite it silently; the change goes to review.

• Clear status: search results say which category each item is in: current, superseded, disputed, open question, or insufficient evidence.

• No services: no database server, no Docker, no background process. One SQLite file plus a folder of originals is all the data; copy the folder to move it.

• Model-agnostic: PMI never calls an LLM itself. The agent you are already using does the reading and understanding. An optional local multilingual embedding model is used only for semantic search.

PMI handles Chinese and English text. The bundled sample data and the three Claude Code skills are written in Chinese.

Contents

1. Quick start (5 minutes)

2. Installation

3. Connecting AI agents

4. Adding knowledge

5. Updating knowledge

6. Deleting knowledge

7. Querying knowledge

8. Write policy and trust

9. Data, backup and migration

10. Command reference

11. Security boundary

12. Troubleshooting

13. Development and project layout

Related MCP server: Memory Cortex

1. Quick start (5 minutes)

Requirements: macOS or Linux, git, and uv. uv provides Python 3.12 automatically.

# 0. Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# 1. Clone and install: dependencies, data folder, `pmi` linked into ~/.local/bin, Claude Code skills
git clone https://github.com/yunzePlaud/personal-memory.git ~/personal-memory
cd ~/personal-memory
./scripts/install.sh            # add --with-model to also download the semantic search model (~220 MB)

# 2. Import the sample data and ask questions (the samples are in Chinese)
pmi import examples/project-a --extract
pmi context "为什么 Project A 不采用方案 B"                    # Why didn't Project A choose option B?
pmi context "Project A 现在什么时候上线"                       # When does Project A launch now?
pmi context "Project A 什么时候上线" --as-of 2026-10-15        # The same question, as of an earlier day

# 3. Connect Claude Code (available in all projects)
claude mcp add --scope user pmi -- ~/personal-memory/pmi mcp

Restart Claude Code and ask: "Why didn't Project A choose option B?" The agent calls memory_get_context first and answers with sources.

The data in examples/ is fictional. To start over, delete the data/ folder and run pmi init.

2. Installation

What scripts/install.sh does

Options:

• --no-skills: do not install the skills.

• --no-semantic: keyword search only, fewer dependencies. Afterwards add export PMI_NO_SEMANTIC=1 to your shell profile, and pass -e PMI_NO_SEMANTIC=1 to claude mcp add; otherwise the first pmi run installs the semantic search dependencies anyway.

• --with-model: also download the semantic search model.

• PMI_BIN_DIR / PMI_SKILLS_DIR: environment variables that change where the links go.

The script is safe to run again. If a real file or folder already exists where a link would go, the script leaves it untouched.

Manual installation

uv sync --frozen --extra semantic
./pmi init
./pmi doctor          # checks Python, SQLite, FTS5, the model and folder permissions
./pmi model download  # optional: semantic search model

./pmi is a launcher script: it sets PMI_HOME to the repository folder and runs PMI with uv. It also finds the repository when called through a symlink such as ~/.local/bin/pmi. Every command accepts --json.

External tools (only when needed)

Configuration (optional)

Copy config/settings.example.toml to config/settings.toml. Common settings:

[embedding]
provider = "none"                 # turn off semantic search; the default is "fastembed"
[capture]
import_roots = ["~/Documents", "~/Desktop", "~/Downloads"]   # folders an agent may ask PMI to read; hidden folders are always refused
[policy]
inferred_create = "review"        # agent-proposed claims without a source quote: review / apply / deny

Never put secrets in the configuration file: the whole folder is meant to be copied around.

3. Connecting AI agents

Every agent starts the PMI MCP server (stdio) with the same command:

command: /absolute/path/to/personal-memory/pmi
args:    ["mcp"]

Claude Code

claude mcp add --scope user pmi -- ~/personal-memory/pmi mcp    # --scope user: available in all projects
claude mcp list                                                 # check that it is connected

install.sh has already installed the 3 skills: /pmi-notion, /pmi-linear and /pmi-slack (see section 4).

Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.pmi]
command = "/Users/<you>/personal-memory/pmi"
args = ["mcp"]

Cursor / Claude Desktop / Gemini CLI / other MCP clients

These clients share the same JSON structure; only the file location differs:

{
  "mcpServers": {
    "pmi": { "command": "/Users/<you>/personal-memory/pmi", "args": ["mcp"] }
  }
}

The 6 MCP tools

The server's instructions field explains how to use them, so a newly connected agent can start right away:

Confirming, deleting and approving are not available over MCP. Only you can do them, from the command line.

Make agents use PMI proactively

Add a paragraph like this to a project's CLAUDE.md / AGENTS.md so agents check PMI first more reliably:

Before answering questions about my past work (requirement background, why a decision was made, who owns what, the current state of a feature), call PMI's `memory_get_context` and cite the sources it returns. If PMI reports insufficient evidence, say so instead of guessing.

Agents and scripts without MCP

Any agent that can run commands can use the CLI:

pmi --json context "some question"

From Python:

from pmi import Memory
with Memory.open("~/personal-memory") as m:
    ctx = m.get_context("Why didn't Project A choose option B?")

4. Adding knowledge

PMI stores data in two layers:

• Sources: the original texts, which serve as evidence.

• Memories: knowledge distilled from sources; every memory quotes a source.

4.1 Import files and folders

pmi import ~/Documents/prds                 # import a folder: Markdown / TXT / PDF / DOCX; GBK-encoded Chinese text works too
pmi import meeting.md --extract             # meeting notes in the convention below become memories automatically
pmi import notes/ --trust external          # mark material written by others as external

On import:

• Hidden files and unsupported formats are skipped, with the reason listed. One broken file does not stop the rest.

• Identical content is deduplicated automatically.

• Importing a file again after it changed stores a new version; the old version is kept.

Meeting notes convention (extracted with --extract, no LLM needed):

---
title: Project A weekly sync
date: 2026-10-01
project: Project A
attendees: [Alice, Bob]
type: meeting
---
# Project A weekly sync 2026-10-01

## Decisions
- [slot: launch-date] Project A will launch on November 15.

## Facts
- The push platform is maintained by Bob's team.

## Action Items
- @Bob finish the integration review by October 10.

Notes on the format:

• Section names can be Decisions, Facts / Context, Action Items / TODO, or their Chinese equivalents (决策, 事实 / 背景 / 结论, 待办 / 行动项).

• [slot: …] is a topic key; see section 5.

• Put a space after @name.

• Free-form documents such as PRDs yield nothing this way. Let an agent distill them instead (see 4.3).

4.2 Store a piece of text

pmi note "Project A's release window moves to Thursdays"
pbpaste | pmi note - --kind document --title "Some PRD" --url "<original link>" --trust external

4.3 Let an agent distill it (recommended)

In Claude Code, say: "Store this PRD in PMI and distill the knowledge." The agent will:

1. Call memory_add_source to store the original text.

2. Call memory_propose to submit memories, each with a verbatim quote.

PMI checks every quote and handles deduplication, superseding and conflicts automatically.

4.4 Import from Notion / Linear / Slack (Claude Code skills)

You can also just say "import this ticket into PMI". All three skills follow the same rules:

• They run only when you explicitly ask for an import. A link that is part of another task ("implement this PRD", "help me reply to this thread") is not stored in PMI.

• They always ask before writing. One confirmation covers both storing the text and distilling it. Say "store the text only" to skip distilling.

• Everything is stored as an external document. Memories backed by these sources cannot automatically change memories you confirmed, or memories backed by your own documents.

• One object, one identity. All link forms of the same page, ticket, PR or thread map to one source identity, such as notion:<page id>, linear:APP-184, github:owner/repo#123 or slack:<channel>/<thread timestamp>. Importing it again creates a new version.

• No personal identifiers are kept. Email addresses and user IDs are not stored; images keep only their caption or file name.

Other agents can follow the steps in integrations/claude-code/skills/*/SKILL.md with their own Notion / Linear / Slack connectors.

4.5 Write memories directly (JSON)

pmi propose ops.json                      # runs as you; takes effect immediately
pmi propose ops.json --as-agent my-bot    # runs as an agent: write policy applies and conflicts go to review

Example ops.json (full example in examples/agent-ops.json):

[
  {"op": "create", "memory": {
    "kind": "decision",
    "content": "Project A sends push notifications through option A (the existing push platform)",
    "slot": "project-a/architecture",
    "entities": [{"name": "Project A", "kind": "project"}],
    "valid_from": "2026-10-01",
    "evidence": [{"source_id": "src_…", "quote": "option A (the existing push platform)"}]
  }}
]

Fields:

• kind is one of episodic (event), semantic (fact), project, person, decision, procedure, preference.

• evidence.quote must appear verbatim in the source named by source_id and be at least 4 characters long.

5. Updating knowledge

Slots: one current conclusion per topic

A slot is a memory's topic key, such as project-a/launch-date. A slot has at most one active memory at any time. When a new claim arrives:

Common update operations

pmi import changed-file.md            # stored as a new version; quoted sentences that disappeared from it are reported
pmi confirm mem_…                     # confirm a memory; agents can no longer change it automatically
pmi review list                       # list pending changes, with the full text and quotes of what would be superseded or activated
pmi review approve prp_…              # approve; the approved memory is marked as confirmed
pmi review reject prp_… --reason "The Slack message was wrong"
pmi show mem_… --history              # full version history and quotes of a memory
pmi entity alias ent_… "alias"        # make different names point to the same person or project

You can also change memories with JSON, through pmi propose or MCP memory_propose:

• Change the content: {"op":"update","id":"mem_…","changes":{"content":"…"}}

• Supersede old memories: {"op":"supersede","old_ids":["mem_…"],"memory":{…}}

• Link two memories: {"op":"link","from_id":"…","to_id":"…","type":"contradicts"}

6. Deleting knowledge

pmi archive mem_… --reason "no longer relevant"     # soft delete: hidden from search by default, can be restored
pmi restore-memory mem_…                            # restore an archived memory

pmi forget mem_… --reason "not needed"              # hard-delete a memory
pmi forget src_… --reason "sensitive"               # hard-delete a source; refused if memories depend on it, listing them
pmi forget src_… --reason "sensitive" --cascade     # also delete the memories that rest only on this source
pmi forget src_… --reason "sensitive" --keep-memories   # keep those memories, downgraded to "inferred"
pmi forget src_… --reason "…" --this-version        # delete only this version (default: every version of the document)

About forgetting:

• Forgetting cannot be undone. Only a tombstone without content remains (id, time, reason).

• The database runs with secure_delete, and forgetting also compacts the search index and truncates the WAL, so the deleted content does not linger in the database files.

• Backups made before forgetting still contain the content. Delete old backups yourself if needed.

7. Querying knowledge

pmi context "When does Project A launch now?"                # assembled context: current, conflicts, history, source passages
pmi context "launch date" --project "Project A" --history
pmi context "launch date" --as-of 2026-10-15                 # answer as of a point in time
pmi search "push platform" --scope sources                   # low-level search
pmi show mem_… src_…                                         # look up by id
pmi list slots | entities | proposals | recent | memories    # browse

Fields in a context result:

• status: active / superseded / disputed.

• verification: user_confirmed / source_backed / inferred.

• trust: the trust level of each quote.

• insufficient_evidence: true: PMI does not have enough evidence to answer. Items found only through entity links or weak semantic similarity are still listed, but do not count as evidence.

8. Write policy and trust

Protected memories are memories you confirmed, or memories backed by a more trusted source.

Trust levels, from highest to lowest:

• owner: content you imported yourself.

• agent: an agent's own analysis.

• external: Slack, web pages, other people's documents, and Notion / Linear imports.

Whether a change takes effect automatically depends on the lowest trust level among the new evidence it brings. Adding a sentence that already exists in the target's own source does not raise the trust level.

9. Data, backup and migration

personal-memory/
├── pmi                         launcher script
├── scripts/install.sh          one-step installer
├── integrations/claude-code/   Claude Code skills (pmi-notion / pmi-linear / pmi-slack)
├── src/  tests/  docs/  examples/
├── config/settings.toml        optional configuration (not committed)
└── data/                       your memory (not committed)
    ├── memory/pmi.db           ← required: the source of truth
    ├── sources/                ← required: original files
    ├── memory/backups/         backups
    ├── index/search.db         disposable: search index, rebuilt automatically
    └── models/                 disposable: embedding model, can be downloaded again

pmi verify            # integrity check: database, hashes, every quote still in its source, version chains, complete forgetting
pmi verify --fix      # also remove orphan files that no source references
pmi backup            # consistent snapshot → data/memory/backups/*.tar.gz (with checksums)
pmi restore <archive> --to ~/pmi-copy
pmi export --out all.jsonl     # full export, independent of format and vendor

Moving to another computer:

1. Run pmi backup first, or make sure no agent is writing.

2. Copy the whole folder to the new computer. .venv/ and data/index/ can be left out.

3. In the new location, run ./scripts/install.sh && pmi verify.

All paths are relative, so the folder can live anywhere.

Switching the embedding model: change [embedding] model in config/settings.toml, then run pmi reindex --vectors. During the rebuild, semantic search is turned off automatically and keyword search keeps working; memories are not affected.

10. Command reference

Global options:

• --home <folder>: the PMI folder; defaults to the repository folder or $PMI_HOME.

• --json: machine-readable JSON output.

11. Security boundary

• Single user, local. Permission checks limit what an agent can do through the tool interface; they are not operating-system isolation. Any local program that can read and write this folder can bypass them. In Claude Code, Claude Code's own permission prompts guard the commands an agent runs.

• A portable folder is not access control. Copying the folder takes all the data with it. If it holds company content (PRDs, Slack), follow your company's data policy before copying it to another device.

• PMI takes no outbound actions. It does not send messages or change other systems. Only two things touch the network: pmi model download, which you run explicitly, and pmi github-pr, which calls your local gh. The package stores no secrets.

• External content is labeled. Content with trust=external is marked in results, together with a notice that the text is data, not instructions. PMI's behavior depends only on who is calling and which operation is requested, never on the content.

• Everything is traceable. Every change is written to an audit log, and every memory has a full version chain.

• Not implemented: multiple users and permission domains, a built-in LLM extractor, an HTTP API, a web UI, automatic Slack / Notion sync.

12. Troubleshooting

13. Development and project layout

uv sync --extra semantic
uv run --frozen --extra semantic pytest -q            # all tests; no network or model needed
uv run --frozen --extra semantic pytest -q -m slow    # tests with the real embedding model; run pmi model download first

Main modules in src/pmi/:

• api.py: the single business entry point.

• evolution.py: superseding, conflict and review rules.

• policy.py: write policy.

• context.py: context assembly.

• search.py: search (FTS5 over CJK bigrams, plus vectors).

• index/: the rebuildable search index.

• mcp_server.py, cli.py: the MCP server and command-line entry points.

• integrations/github_pr.py: GitHub PR to Markdown.

Other folders and files:

• tests/test_acceptance.py: 10 end-to-end acceptance scenarios.

• docs/design/: the design document (in Chinese).

• docs/implementation-notes.md: trade-offs made during implementation (in Chinese).

• docs/requirements.md: the original requirements (in Chinese).

Dependencies: mcp, pypdf, python-docx, pyyaml, and optionally fastembed; all versions are pinned in uv.lock.

License: MIT