memory-passport 0.2.0

Every assistant remembers you. None of them will tell the others.

ChatGPT knows you're vegetarian. Claude knows about the ledger rewrite. Cursor knows you hate semicolons.
Switch products and you start from zero. memory-passport is a plain-text format, a spec, and a CLI that moves it all.

⏱️ 60-second quickstart

pip install memory-passport            # or: uv tool install memory-passport

# 1. Turn a ChatGPT data export into a vault (memories are hiding inside conversations.json)
passport import chatgpt-export.zip --out passport

# 2. Check it against the spec
passport validate passport

# 3. Paste it into Claude (Settings → Memory → Start import)
passport export passport --to claude | pbcopy

That is the whole loop. Your vault is a folder of markdown files you can read, edit, and commit to git.

🗂️ What a passport looks like

passport/
├── passport.yaml          # spec_version, allow_health
├── profile.md             # who you are
├── preferences.md         # how you like assistants to behave
├── people/priya-nair.md   # one file per person
├── topics/e-ink-devices.md
└── areas/ledger-rewrite.md   # one file per project

Every file is YAML frontmatter plus bullet lines. Every bullet says where it came from:

---
name: Priya Nair
description: Sam's manager; sets quarterly priorities and reviews design docs.
sources: [chatgpt, claude]
aliases: [Priya, PN]
updated: "2026-06-11"
kind: person
---

- [stated] Prefers decisions written up as one-page ADRs before a meeting.
- [inferred] Likely based in the Edinburgh office, given meeting times. <!-- src: chatgpt, 2026-05-02 -->

No product records provenance today. They should. Until they do, the importers tag conservatively and the exporters hedge anything that was only a guess ("Possibly: …") so a wrong inference never gets promoted to fact on the way in to the next assistant.

🚫 What a passport refuses to carry

A passport is designed to be pasted into many products, so it is the worst possible place for anything you would not hand to a third party. The validator rejects these outright:

Importers redact the span (has a Monzo card [redacted card-number]) and tell you, so the useful half of the sentence survives. Health is the one opt-in category (--allow-health), because an assistant that knows about your dietary restriction is genuinely more useful. The rest have no everyday use. Full reasoning in SPEC.md §7.

🔀 Merge without losing, diff without squinting

Two vaults from two products will disagree. merge never picks silently: the same fact with different tags keeps the more trusted one, new facts are added, and contradictions get git-style conflict markers that fail validation until you resolve them. "Lives in Manchester" and "User is based in Manchester" count as the same fact; a small phrasing table catches the common rewordings without a model.

passport diff vault-a vault-b            # + added, - removed, ~ retagged
passport merge vault-a vault-b --out merged

🧠 Live memory, not just luggage

Once you have a vault, keep using it. Add facts by hand, ask it questions, and let your assistants read and write it directly over MCP.

passport add passport "Priya moved to the Edinburgh office." --to person:Priya
passport show passport priya
passport show passport -q "british english"
passport forget passport "works four days a week"
passport validate passport --stale 365       # flag observed/inferred facts older than a year

MCP server. pip install "memory-passport[mcp]" gives you passport-mcp with four tools: list_subjects, read_memory, remember, forget. Register it once and Claude Code, Cursor or Claude Desktop use the same plain files you edit by hand:

claude mcp add passport -e PASSPORT_VAULT=~/passport -- passport-mcp

Everything a client writes goes through the same exclusion and dedupe rules as the CLI. A card number pasted into remember comes out as [redacted card-number]; a health diagnosis is refused.

Prompt export. passport export passport --to prompt --budget 2000 renders a <user_memory> block for any model, API call or agent persona. Over budget, it drops inferred facts first, then observed, then the oldest stated.

🌐 Try it in the browser

mohitagw15856.github.io/memory-passport runs the real validator, importers and exporters in your browser via Pyodide. Pick a vault folder, paste a memory list, download the result. Nothing is uploaded.

🧭 Every command

🧳 Where the memories actually are

Getting memory out of products is the annoying part. Here is what each one really offers, and what the passport does with it.

Corrections welcome. Products change their exports without notice; each importer's module docstring says exactly which fields it reads, and the fixtures in tests/fixtures/ mirror the real layouts.

🔌 Pluggable

Adding a product is one class with detect() and load(), registered as an entry point. No fork needed:

[project.entry-points."memory_passport.importers"]
acme = "passport_acme:AcmeImporter"

passport import --from acme will find it. The walkthrough is in CONTRIBUTING.md.

📐 The spec

SPEC.md defines the layout, the frontmatter (with a JSON Schema), fact lines, the three tags, the exclusions and why, merge semantics, and what the format deliberately cannot express. docs/ADR-001.md explains why markdown plus frontmatter beat JSON.

The examples/sample-vault/ folder is a complete, valid vault to poke at.

🛠️ Developing

git clone https://github.com/mohitagw15856/memory-passport && cd memory-passport
uv sync --group dev
uv run pytest -q          # fixture exports for every importer
uv run ruff check .

📜 Licence

MIT © mohitagw15856. Your memories are yours; this just helps them travel.