# macpaw/portable-memory architecture

> Architecture diagram of the GitHub repository macpaw/portable-memory, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macpaw/portable-memory
- Repository: https://github.com/macpaw/portable-memory

## Overview

Portable Memory is a local-first Python SDK and CLI for moving AI memory between vendors in a verifiable `.mem` bundle. Users paste or ingest an export, then inspect, validate, and render it; adopters can export from or merge into their own store. The graph separates adapters, bundle workflows, and the shared format and trust primitives. Edges follow the README or sampled source references; some CLI details and other unsampled implementations are represented only at their documented boundaries.

Main entry points: [`portable_memory/cli.py`](https://github.com/macpaw/portable-memory/blob/main/portable_memory/cli.py) (CLI commands), [`portable_memory/exporter.py`](https://github.com/macpaw/portable-memory/blob/main/portable_memory/exporter.py) (Bundle exporter), [`portable_memory/importer.py`](https://github.com/macpaw/portable-memory/blob/main/portable_memory/importer.py) (Bundle importer), [`portable_memory/records.py`](https://github.com/macpaw/portable-memory/blob/main/portable_memory/records.py) (Record models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["User workflows"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_adapters["Memory adapters"]
  node_transfer["Text transfer<br/>[transfer.py]"]
  node_openai["OpenAI adapter<br/>[openai.py]"]
  node_claude["Claude adapter<br/>[claude.py]"]
  node_mem0["Mem0 adapter<br/>[mem0.py]"]
  node_adapter_api["Adapter dispatch<br/>[__init__.py]"]
end

subgraph group_bundle["Bundle operations"]
  node_exporter["Bundle exporter<br/>[exporter.py]"]
  node_importer["Bundle importer<br/>[importer.py]"]
  node_validator["Bundle validator<br/>[validator.py]"]
  node_store["Store interface<br/>[store.py]"]
  node_memory_store["In-memory store<br/>[inmemory.py]"]
end

subgraph group_format["Portable format"]
  node_format_model["Bundle format<br/>[format.py]"]
  node_records["Record models<br/>[records.py]"]
  node_codec["Canonical codec<br/>[_codec.py]"]
  node_interop["Extension fields<br/>[interop.py]"]
end

subgraph group_trust["Integrity and governance"]
  node_hashing["Content hashing<br/>[hashing.py]"]
  node_tombstone["Deletion records<br/>[tombstone.py]"]
  node_signing["Ed25519 signing<br/>[signing.py]"]
end

node_user(("Memory owner"))

node_user -->|"runs commands"| node_cli
node_cli -->|"parses pasted text"| node_transfer
node_cli -->|"ingests export"| node_openai
node_cli -->|"ingests memory"| node_claude
node_cli -->|"ingests memories"| node_mem0
node_cli -->|"dispatches adapters"| node_adapter_api
node_adapter_api -->|"exposes adapter"| node_transfer
node_adapter_api -->|"exposes adapter"| node_openai
node_adapter_api -->|"exposes adapter"| node_claude
node_adapter_api -->|"exposes adapter"| node_mem0
node_cli -->|"exports bundle"| node_exporter
node_cli -->|"imports bundle"| node_importer
node_cli -->|"validates bundle"| node_validator
node_exporter -->|"reads records"| node_store
node_importer -->|"applies records"| node_store
node_memory_store -->|"implements interface"| node_store
node_exporter -->|"writes bundle layout"| node_format_model
node_importer -->|"reads bundle layout"| node_format_model
node_validator -->|"checks format"| node_format_model
node_exporter -->|"encodes records"| node_codec
node_importer -->|"decodes records"| node_codec
node_validator -->|"decodes streams"| node_codec
node_exporter -->|"checksums files"| node_hashing
node_validator -->|"verifies checksums"| node_hashing
node_exporter -->|"merges extensions"| node_interop
node_importer -->|"preserves extensions"| node_interop
node_importer -->|"applies deletions"| node_tombstone
node_exporter -->|"signs manifest"| node_signing
node_importer -->|"verifies signatures"| node_signing
node_validator -->|"checks authenticity"| node_signing
node_transfer -->|"creates episodes"| node_records
node_openai -->|"creates records"| node_records
node_claude -->|"creates records"| node_records
node_mem0 -->|"creates records"| node_records
node_exporter -->|"serializes records"| node_records
node_importer -->|"materializes records"| node_records
node_user -.->|"renders memory text"| node_cli

click node_cli "https://github.com/macpaw/portable-memory/blob/main/portable_memory/cli.py"
click node_transfer "https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/transfer.py"
click node_openai "https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/openai.py"
click node_claude "https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/claude.py"
click node_mem0 "https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/mem0.py"
click node_adapter_api "https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/__init__.py"
click node_exporter "https://github.com/macpaw/portable-memory/blob/main/portable_memory/exporter.py"
click node_importer "https://github.com/macpaw/portable-memory/blob/main/portable_memory/importer.py"
click node_validator "https://github.com/macpaw/portable-memory/blob/main/portable_memory/validator.py"
click node_store "https://github.com/macpaw/portable-memory/blob/main/portable_memory/store.py"
click node_memory_store "https://github.com/macpaw/portable-memory/blob/main/portable_memory/inmemory.py"
click node_format_model "https://github.com/macpaw/portable-memory/blob/main/portable_memory/format.py"
click node_records "https://github.com/macpaw/portable-memory/blob/main/portable_memory/records.py"
click node_codec "https://github.com/macpaw/portable-memory/blob/main/portable_memory/_codec.py"
click node_interop "https://github.com/macpaw/portable-memory/blob/main/portable_memory/interop.py"
click node_hashing "https://github.com/macpaw/portable-memory/blob/main/portable_memory/hashing.py"
click node_tombstone "https://github.com/macpaw/portable-memory/blob/main/portable_memory/tombstone.py"
click node_signing "https://github.com/macpaw/portable-memory/blob/main/portable_memory/signing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli toneBlue
class node_transfer,node_openai,node_claude,node_mem0,node_adapter_api toneAmber
class node_exporter,node_importer,node_validator,node_store,node_memory_store toneMint
class node_format_model,node_records,node_codec,node_interop toneRose
class node_hashing,node_tombstone,node_signing,node_user toneIndigo
```

## Components

### User workflows

- [CLI commands](https://github.com/macpaw/portable-memory/blob/main/portable_memory/cli.py): `portable_memory/cli.py`

### Memory adapters

- [Text transfer](https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/transfer.py): `portable_memory/adapters/transfer.py`
- [OpenAI adapter](https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/openai.py): `portable_memory/adapters/openai.py`
- [Claude adapter](https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/claude.py): `portable_memory/adapters/claude.py`
- [Mem0 adapter](https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/mem0.py): `portable_memory/adapters/mem0.py`
- [Adapter dispatch](https://github.com/macpaw/portable-memory/blob/main/portable_memory/adapters/__init__.py): `portable_memory/adapters/__init__.py`

### Bundle operations

- [Bundle exporter](https://github.com/macpaw/portable-memory/blob/main/portable_memory/exporter.py): `portable_memory/exporter.py`
- [Bundle importer](https://github.com/macpaw/portable-memory/blob/main/portable_memory/importer.py): `portable_memory/importer.py`
- [Bundle validator](https://github.com/macpaw/portable-memory/blob/main/portable_memory/validator.py): `portable_memory/validator.py`
- [Store interface](https://github.com/macpaw/portable-memory/blob/main/portable_memory/store.py): `portable_memory/store.py`
- [In-memory store](https://github.com/macpaw/portable-memory/blob/main/portable_memory/inmemory.py): `portable_memory/inmemory.py`

### Portable format

- [Bundle format](https://github.com/macpaw/portable-memory/blob/main/portable_memory/format.py): `portable_memory/format.py`
- [Record models](https://github.com/macpaw/portable-memory/blob/main/portable_memory/records.py): `portable_memory/records.py`
- [Canonical codec](https://github.com/macpaw/portable-memory/blob/main/portable_memory/_codec.py): `portable_memory/_codec.py`
- [Extension fields](https://github.com/macpaw/portable-memory/blob/main/portable_memory/interop.py): `portable_memory/interop.py`

### Integrity and governance

- [Content hashing](https://github.com/macpaw/portable-memory/blob/main/portable_memory/hashing.py): `portable_memory/hashing.py`
- [Deletion records](https://github.com/macpaw/portable-memory/blob/main/portable_memory/tombstone.py): `portable_memory/tombstone.py`
- [Ed25519 signing](https://github.com/macpaw/portable-memory/blob/main/portable_memory/signing.py): `portable_memory/signing.py`

### Other components

- **Memory owner**

## Connections

- Memory owner → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Text transfer: parses pasted text (evidence: `portable_memory/cli.py`)
- CLI commands → OpenAI adapter: ingests export (evidence: `portable_memory/cli.py`)
- CLI commands → Claude adapter: ingests memory (evidence: `portable_memory/cli.py`)
- CLI commands → Mem0 adapter: ingests memories (evidence: `portable_memory/cli.py`)
- CLI commands → Adapter dispatch: dispatches adapters (evidence: `portable_memory/cli.py`)
- Adapter dispatch → Text transfer: exposes adapter (evidence: `portable_memory/adapters/__init__.py`)
- Adapter dispatch → OpenAI adapter: exposes adapter (evidence: `portable_memory/adapters/__init__.py`)
- Adapter dispatch → Claude adapter: exposes adapter (evidence: `portable_memory/adapters/__init__.py`)
- Adapter dispatch → Mem0 adapter: exposes adapter (evidence: `portable_memory/adapters/__init__.py`)
- CLI commands → Bundle exporter: exports bundle (evidence: `portable_memory/cli.py`)
- CLI commands → Bundle importer: imports bundle (evidence: `portable_memory/cli.py`)
- CLI commands → Bundle validator: validates bundle (evidence: `portable_memory/cli.py`)
- Bundle exporter → Store interface: reads records (evidence: `portable_memory/exporter.py`)
- Bundle importer → Store interface: applies records (evidence: `portable_memory/importer.py`)
- In-memory store → Store interface: implements interface (evidence: `portable_memory/inmemory.py`)
- Bundle exporter → Bundle format: writes bundle layout (evidence: `portable_memory/exporter.py`)
- Bundle importer → Bundle format: reads bundle layout (evidence: `portable_memory/importer.py`)
- Bundle validator → Bundle format: checks format (evidence: `portable_memory/validator.py`)
- Bundle exporter → Canonical codec: encodes records (evidence: `portable_memory/exporter.py`)
- Bundle importer → Canonical codec: decodes records (evidence: `portable_memory/importer.py`)
- Bundle validator → Canonical codec: decodes streams (evidence: `portable_memory/validator.py`)
- Bundle exporter → Content hashing: checksums files (evidence: `portable_memory/exporter.py`)
- Bundle validator → Content hashing: verifies checksums (evidence: `portable_memory/validator.py`)
- Bundle exporter → Extension fields: merges extensions (evidence: `portable_memory/exporter.py`)
- Bundle importer → Extension fields: preserves extensions (evidence: `portable_memory/importer.py`)
- Bundle importer → Deletion records: applies deletions (evidence: `portable_memory/importer.py`)
- Bundle exporter → Ed25519 signing: signs manifest (evidence: `portable_memory/exporter.py`)
- Bundle importer → Ed25519 signing: verifies signatures (evidence: `portable_memory/importer.py`)
- Bundle validator → Ed25519 signing: checks authenticity (evidence: `portable_memory/validator.py`)
- Text transfer → Record models: creates episodes (evidence: `portable_memory/adapters/transfer.py`)
- OpenAI adapter → Record models: creates records (evidence: `portable_memory/adapters/openai.py`)
- Claude adapter → Record models: creates records (evidence: `portable_memory/adapters/claude.py`)
- Mem0 adapter → Record models: creates records (evidence: `portable_memory/adapters/mem0.py`)
- Bundle exporter → Record models: serializes records (evidence: `portable_memory/exporter.py`)
- Bundle importer → Record models: materializes records (evidence: `portable_memory/importer.py`)
- Memory owner → CLI commands: renders memory text (evidence: `README.md`)
