memory-passport 0.2.0__tar.gz

memory_passport-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+_site/

memory_passport-0.2.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0 — 2026-09-22
+
+- `passport show`, `passport add`, `passport forget`: use the vault day to day, not just for migration.
+- `passport-mcp`: an MCP server (`pip install "memory-passport[mcp]"`) exposing `list_subjects`, `read_memory`, `remember`, `forget`.
+- `--to prompt` exporter with `--budget`, a `<user_memory>` block for any model or agent.
+- Gemini and Copilot importers from pasted text (`TextListImporter` base for others).
+- Redaction instead of dropping for card, bank, ID and secret spans; health is still dropped.
+- Semantic dedupe: common rewordings ("based in" / "lives in") collapse to one fact in import, merge and diff.
+- `passport validate --stale DAYS` warns about old observed/inferred facts; stated facts never go stale.
+- `passport inspect` reports what an export contains, for bug reports when a product changes its format.
+- Browser playground at mohitagw15856.github.io/memory-passport (Pyodide; nothing uploaded).
+- Release workflow with PyPI trusted publishing on `v*` tags.
+
+## 0.1.0 — 2026-09-22
+
+- Spec 0.1, JSON Schemas, validator, ChatGPT/Claude/markdown importers, five exporters, merge and diff.

memory_passport-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,116 @@
+# Contributing
+
+Thanks for helping make memory portable. The most useful contribution is an importer or exporter for a product we do not cover yet, and this guide is mostly about that.
+
+## Setup
+
+```bash
+git clone https://github.com/mohitagw15856/memory-passport
+cd memory-passport
+uv sync --group dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+```
+
+Python 3.11+. British English in prose and docstrings. Keep the CLI output terse.
+
+## Adding an importer
+
+An importer turns a product's export into a `Vault`. Two ways to ship one:
+
+- **In this repo:** add `memory_passport/importers/<product>.py` and register it in `registry.py` and `pyproject.toml`.
+- **In your own package:** expose an entry point in the `memory_passport.importers` group. `passport import --from <name>` will find it with no change here.
+
+### 1. Find the real export format
+
+Do not guess. Download an export from the product, open it, and put a **trimmed, fake-data** copy in `tests/fixtures/<product>/`. Every importer in this repo is written against a fixture that mirrors the real file layout. Note where memory actually lives; often it is not where you expect (ChatGPT's is inside `conversations.json`, addressed to a tool called `bio`).
+
+### 1a. Shortcut for products with no export
+
+If the product will only *list* its memories when asked (Gemini, Copilot), subclass `TextListImporter` instead and set `name`, `help` and `prompt`. See `importers/gemini.py`; it is nine lines.
+
+### 2. Implement the class
+
+```python
+# memory_passport/importers/acme.py
+from pathlib import Path
+
+from memory_passport.importers.base import Importer, ImportOptions, ImportResult
+from memory_passport.importers.builder import VaultBuilder
+from memory_passport.importers.text import is_hedged, tidy
+from memory_passport.model import Fact
+
+
+class AcmeImporter(Importer):
+    name = "acme"                      # used by --from and written into `sources`
+    help = "Acme Assistant memory export (memories.json)"
+
+    def detect(self, path: Path) -> bool:
+        return path.name == "memories.json"
+
+    def load(self, path: Path, options: ImportOptions) -> ImportResult:
+        b = VaultBuilder(self.name, allow_health=options.allow_health, do_route=options.route)
+        notes = []
+        for entry in read_acme(path):          # your parsing
+            text = tidy(entry["text"])
+            tag = "inferred" if is_hedged(text) else "stated"   # document your rule!
+            b.add(Fact(tag, text, date=entry.get("date")))
+        notes.append(f"read {len(...)} memories")
+        return ImportResult(vault=b.build(), notes=notes, dropped=b.dropped)
+```
+
+`VaultBuilder` does the boring parts: exclusion scanning (facts that trip a detector go to `dropped`, never into the vault), dedupe by fact key, routing to `people/`, `topics/`, `areas/` or `preferences.md` (pass `to=Route(...)` to override), and frontmatter generation.
+
+### 3. Decide the provenance rule, and write it down
+
+The spec says importers MUST default to `[inferred]` unless they have a documented reason to do better. Put the reason in the module docstring. "The product only stores what the user typed" is a reason. "It is probably fine" is not.
+
+### 4. Register it
+
+In-repo:
+
+```python
+# registry.py
+from memory_passport.importers.acme import AcmeImporter
+return [ChatGPTImporter, ClaudeImporter, MarkdownImporter, AcmeImporter]
+```
+
+```toml
+# pyproject.toml
+[project.entry-points."memory_passport.importers"]
+acme = "memory_passport.importers.acme:AcmeImporter"
+```
+
+External package:
+
+```toml
+[project.entry-points."memory_passport.importers"]
+acme = "passport_acme:AcmeImporter"
+```
+
+### 5. Test it
+
+`tests/test_importers.py` shows the pattern. At minimum:
+
+- `detect()` is true for the fixture and false for the other fixtures.
+- The vault it produces passes `validate_vault()` with no errors.
+- A fact that should be excluded (put a test card number in the fixture) ends up in `dropped`, not in the vault.
+- Tags are what your documented rule says.
+
+### 6. Update the README comparison table
+
+Add a row for the product: what its memory can and cannot express, and how the export and import actually work for users.
+
+## Adding an exporter
+
+Same shape, smaller. Subclass `Exporter` in `memory_passport/exporters/`, return an `ExportResult` whose `files` map paths to content (use the single key `"-"` for "print to stdout"), and register it. Read `base.fact_sentence()` before writing: it is how inferred facts get hedged for products that have no provenance, and you should use it rather than dropping the distinction.
+
+## Changing the spec
+
+Open an issue first. SPEC.md is versioned; anything that would break a 0.1 reader is a major bump and needs an ADR in `docs/`.
+
+## Pull requests
+
+- One importer, exporter or fix per PR.
+- CI runs ruff and pytest on 3.11, 3.12 and 3.13; it must be green.
+- Commit messages in the imperative mood.

memory_passport-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mohitagw15856
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memory_passport-0.2.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.5
+Name: memory-passport
+Version: 0.2.0
+Summary: A portable, plain-text format for AI assistant memory, with converters.
+Project-URL: Homepage, https://github.com/mohitagw15856/memory-passport
+Project-URL: Issues, https://github.com/mohitagw15856/memory-passport/issues
+Author: mohitagw15856
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,chatgpt,claude,markdown,memory,portability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="memory-passport: your AI memory, yours to take anywhere" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/mohitagw15856/memory-passport/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mohitagw15856/memory-passport/actions/workflows/ci.yml/badge.svg"></a>
+  <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-3776ab?logo=python&logoColor=white">
+  <img alt="Spec 0.1" src="https://img.shields.io/badge/spec-0.1-7c3aed">
+  <a href="LICENSE"><img alt="MIT" src="https://img.shields.io/badge/licence-MIT-34d399"></a>
+  <img alt="British English" src="https://img.shields.io/badge/spelling-British%20🇬🇧-f472b6">
+</p>
+
+<h3 align="center">Every assistant remembers you. None of them will tell the others.</h3>
+
+<p align="center">
+ChatGPT knows you're vegetarian. Claude knows about the ledger rewrite. Cursor knows you hate semicolons.<br>
+Switch products and you start from zero. <b>memory-passport</b> is a plain-text format, a spec, and a CLI that moves it all.
+</p>
+
+<p align="center">
+  <img src="docs/assets/flow.svg" alt="Silos in, one vault, any product out" width="100%">
+</p>
+
+## ⏱️ 60-second quickstart
+
+```bash
+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.
+
+<p align="center">
+  <img src="docs/assets/import.gif" alt="passport import turning a ChatGPT export into a vault" width="90%">
+</p>
+
+## 🗂️ 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**:
+
+```markdown
+---
+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 -->
+```
+
+<p align="center">
+  <img src="docs/assets/tags.svg" alt="stated, observed and inferred tags" width="100%">
+</p>
+
+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:
+
+<p align="center">
+  <img src="docs/assets/excluded.svg" alt="Excluded categories" width="100%">
+</p>
+
+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](SPEC.md#7-excluded-categories).
+
+<p align="center">
+  <img src="docs/assets/validate.gif" alt="passport validate catching a card number, then exporting for Claude" width="90%">
+</p>
+
+## 🔀 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.
+
+<p align="center">
+  <img src="docs/assets/merge.gif" alt="passport diff and merge with a conflict" width="90%">
+</p>
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+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](https://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
+
+| Command | What it does |
+|---|---|
+| `passport validate <dir> [--strict] [--json]` | Check a vault against the spec. Exit 1 on errors. |
+| `passport import <export> [--from chatgpt\|claude\|gemini\|copilot\|markdown] [--out dir]` | Build a vault. Auto-detects the source when it can. |
+| `passport import … --memory-text memories.txt` | Combine an export with a pasted memory list. |
+| `passport import … --no-route` | Skip the people/topics/areas sorting; everything in `profile.md`. |
+| `passport export <dir> --to prompt\|chatgpt\|claude\|claude-code\|cursor\|markdown [--out path] [--budget N]` | Paste-ready text or files for that product. |
+| `passport merge <a> <b> --out merged` | Merge with conflict markers. Exit 3 if any conflicts. |
+| `passport diff <a> <b> [--json]` | Fact-level diff. Exit 1 if they differ. |
+| `passport show <dir> [subject] [-q words]` | List subjects, print one, or search facts. |
+| `passport add <dir> "fact" [--to subject] [--tag] [--section]` | Append one dated fact, with exclusions applied. |
+| `passport forget <dir> "fact"` | Remove a fact by text (loose match). |
+| `passport inspect <export>` | Say what an export contains without importing it. Paste into bug reports. |
+| `passport importers` / `passport exporters` | List what is installed, including plugins. |
+
+## 🧳 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.
+
+| Product | Export exists? | Import exists? | Where memory hides | Provenance | Per-subject structure | Hand-editable | Sensitive-data control |
+|---|---|---|---|---|---|---|---|
+| **ChatGPT** | Data export zip, but no memory file. Memories are recoverable from `conversations.json` as messages to the `bio` tool, or copy the *Manage memories* list. | No. Custom instructions (2 × 1,500 chars) or "remember this" in chat. | flat list of sentences | none | none | via settings UI only | delete individual memories |
+| **Claude** (claude.ai) | Copy from *Settings → Memory*, or ask it to write memories out verbatim. Data export has projects but no memory. | Yes: *Settings → Memory → Start import* (experimental). | prose summary | none | by topic in the summary | edit the summary text | "include sensitive topics" toggle |
+| **Claude Code** | It is already files: `~/.claude/projects/<p>/memory/*.md` with frontmatter. | Drop files in the folder. | markdown files | none, but a `type` field | one file per memory | yes | none |
+| **Cursor** | No user memory; project rules in `.cursor/rules/*.mdc`. | Write a rule file. | rule files per repo | none | per repo | yes | none |
+| **Gemini** | No export. Copy *Saved info* or ask it to list everything; `--from gemini`. | No. | Saved Info list | none | none | via settings UI | delete individual items |
+| **Copilot** | No export. Ask it to list its memories; `--from copilot`. | No. | flat list | none | none | via settings UI | delete individual items |
+| **Hermes Agent / custom bots** | Whatever you built; usually a markdown folder. | Same. | your call | your call | your call | yes | your call |
+| **memory-passport** | It *is* the export. | It *is* the import. | `profile.md`, `preferences.md`, `people/`, `topics/`, `areas/` | `[stated]` `[observed]` `[inferred]` + per-fact source and date | one file per subject, five kinds | yes, it is markdown | validator refuses cards, IDs, secrets; health opt-in |
+
+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:
+
+```toml
+[project.entry-points."memory_passport.importers"]
+acme = "passport_acme:AcmeImporter"
+```
+
+`passport import --from acme` will find it. The walkthrough is in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## 📐 The spec
+
+[SPEC.md](SPEC.md) defines the layout, the frontmatter (with a [JSON Schema](spec/frontmatter.schema.json)), fact lines, the three tags, the exclusions and why, merge semantics, and what the format deliberately cannot express. [docs/ADR-001.md](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
+
+```bash
+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](https://github.com/mohitagw15856). Your memories are yours; this just helps them travel.

memory_passport-0.2.0/PLAN.md

@@ -0,0 +1,111 @@
+# memory-passport — plan
+
+Portable AI-assistant memory: one plain-text format any product can export to and import from, plus converters.
+
+## 1. Schema
+
+### Vault layout
+
+```
+vault/
+  profile.md              # who the user is (role, location, languages, timezone)
+  preferences.md          # how they like things done (tone, formats, tools, workflows)
+  people/<slug>.md        # one file per person (partner, colleague, client)
+  topics/<slug>.md        # one file per domain of interest or expertise
+  areas/<slug>.md         # one file per ongoing project or responsibility
+  passport.yaml           # vault manifest: spec_version, created, exported_by
+```
+
+Slugs are lower-case kebab-case ASCII. `profile.md` and `preferences.md` are singletons; the three folders hold zero or more files.
+
+### Frontmatter (YAML)
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | string | yes | Human-readable subject name |
+| `description` | string | yes | One line, used for recall ranking |
+| `sources` | list of strings | yes | Products this file draws from, e.g. `chatgpt`, `claude`, `claude-code`, `cursor`, `manual` |
+| `aliases` | list of strings | no | Other names for the subject |
+| `updated` | ISO 8601 date | yes | Last time any fact line changed |
+| `kind` | enum | yes | `profile`, `preferences`, `person`, `topic`, `area` — derived from path, but stored so a file is self-describing when moved |
+
+A JSON Schema (draft 2020-12) in `spec/frontmatter.schema.json` is the normative definition; SPEC.md prose explains it.
+
+### Body
+
+- Markdown. Optional `##` sections for grouping; sections are free-form and not part of the spec.
+- Every fact is one bullet line: `- [tag] fact text` where tag is `stated`, `observed`, or `inferred`.
+  - `[stated]` — the user said it explicitly.
+  - `[observed]` — the product saw it happen (files edited, timezone of activity, tools used).
+  - `[inferred]` — the product guessed it from patterns. Least trusted; importers should default here when the source product does not distinguish.
+- Optional trailing metadata on a fact line: `<!-- src: chatgpt, 2025-11-03 -->` (kept as an HTML comment so it survives any markdown renderer and can be stripped for paste-export).
+- Lines that are not fact lines (headings, blank, prose) are allowed but the validator warns if a bullet lacks a tag.
+
+### Exclusions
+
+The spec forbids by default, and the validator rejects: government ID numbers, payment card / bank account numbers, passwords and API keys, and health diagnoses / medications. Detection is regex plus a small keyword list; health can be opted in per vault via `passport.yaml: allow_health: true`. Rationale in SPEC.md: a passport is designed to be pasted into many products, so it is the worst place to keep anything you would not want a third party to hold; the format should make the safe thing the default.
+
+## 2. Converter architecture
+
+```
+memory_passport/
+  model.py        # Vault, MemoryFile, Fact dataclasses; parse/serialise
+  schema.py       # loads JSON Schema; validate_frontmatter()
+  validate.py     # structural + provenance + exclusion checks -> list[Issue]
+  exclusions.py   # sensitive-data detectors
+  merge.py        # three-way-ish merge with <<<<<<< a / ======= / >>>>>>> b markers on conflicting fact lines
+  diff.py         # per-file, per-fact added/removed/changed
+  importers/
+    base.py       # class Importer(Protocol): name, detect(path) -> bool, load(path) -> Vault
+    registry.py   # entry-point group `memory_passport.importers` + built-ins
+    chatgpt.py
+    claude.py
+    markdown.py
+  exporters/
+    base.py       # class Exporter(Protocol): name, render(vault) -> str | Path
+    registry.py
+    chatgpt.py    # paste-ready block for Custom Instructions / "remember this"
+    claude.py     # paste-ready block for Claude project instructions / user preferences
+    claude_code.py# writes CLAUDE.md-style + memory/*.md
+    cursor.py     # .cursor/rules/user.mdc
+    markdown.py   # identity export
+  cli.py          # Typer: validate, import, export, merge, diff, list-importers
+```
+
+Importers are pluggable two ways: register in `registry.py`, or expose a `memory_passport.importers` entry point in any third-party package. `passport import --from <name>` looks up the registry by name.
+
+### Real export formats (verified before coding; to be re-checked with web search at implementation time)
+
+**ChatGPT** — the data export zip contains `conversations.json`, `user.json`, `message_feedback.json`, `shared_conversations.json`, `chat.html`. There is no memory file. Memories are recoverable from `conversations.json`: when ChatGPT saves a memory it emits an assistant message with `recipient: "bio"` whose `content.parts[0]` is the memory sentence. The importer will:
+1. Walk every conversation's `mapping`, collect messages where `author.role == "assistant"` and `recipient == "bio"`.
+2. Also accept a plain-text file pasted from Settings → Personalisation → Manage memories (one memory per line), because many users will find that easier.
+3. Default tag `[stated]` for bio entries phrased "User said/prefers", `[inferred]` otherwise; heuristic and documented.
+4. Route each memory to a file by simple classifier (name mentions → people/, "working on/project" → areas/, "prefers/likes" → preferences.md, else profile.md). Anything unrouted lands in `profile.md` under `## Unsorted`.
+
+**Claude** — two real inputs:
+1. claude.ai data export zip: `conversations.json` (list of conversations with `chat_messages[].text`, `sender`), `projects.json`, `users.json`. No memory file. The importer extracts `projects.json` prompt templates as `[stated]` preferences and offers `--from claude --memory-text <file>` for the memory summary pasted from Settings → Memory.
+2. Claude Code auto-memory dir (`~/.claude/projects/<slug>/memory/*.md`, frontmatter `name`, `description`, `metadata.type` in `user|feedback|project|reference`) plus any `CLAUDE.md`. This is a near-native mapping: `user` → profile/preferences, `project` → areas/, `reference` → topics/, `feedback` → preferences. Tag `[stated]`.
+
+**markdown** — any folder of `.md` files; frontmatter fields present are kept, missing ones synthesised; untagged bullets become `[inferred]` with a warning.
+
+### Exporters
+
+Each exporter renders the vault into what the target accepts, noting the target's limits in the README comparison table (e.g. ChatGPT Custom Instructions ≈ 1,500 chars each box, no provenance; Claude user preferences free text; Cursor rules files; Hermes/custom bots = the markdown vault itself).
+
+## 3. MVP cut
+
+Ship in this order, stopping where you asked:
+
+1. **Spec + validator** — SPEC.md, JSON Schema, `model.py`, `validate.py`, `exclusions.py`, `passport validate`, tests, examples/sample-vault. **→ Stop and show you the spec.**
+2. **First importer: ChatGPT** — zip + pasted-memories text, fixture export in `tests/fixtures/chatgpt/`. **→ Stop after it works.**
+3. Claude importer (export zip + Claude Code memory dir), markdown importer.
+4. Exporters (markdown, claude, claude-code, chatgpt, cursor).
+5. `merge` and `diff`.
+6. README quickstart + comparison table, CONTRIBUTING.md, docs/ADR-001.md, CI (ruff + pytest on 3.11–3.13), LICENSE.
+
+Out of scope for MVP: Gemini/Cursor importers (no stable export), semantic dedupe on merge (exact-line and normalised-whitespace only), encryption.
+
+## Tooling
+
+- Python ≥ 3.11, `uv` for env, `pyproject.toml` (hatchling), deps: `typer`, `pyyaml`, `jsonschema`, `python-frontmatter`. Dev: `pytest`, `ruff`.
+- British English in all prose; MIT, author mohitagw15856.