Skip to main content

AI Agent Portable Memory

One install. Any AI agent. Memory that follows you everywhere.

Install once, set one API key, and your context is automatically saved and restored — across Claude Code, GitHub Copilot CLI, Codex, Cursor, Windsurf, or any agent that uses the Claude Code hook protocol.

No per-agent config. No separate commands per tool. One unified memory store.


The Problem

Every AI session starts blank. You lose:

  • What you were building
  • Decisions you already made
  • Where you stopped

Copy-pasting raw chat logs wastes too many context tokens and is unmanageable.

The Solution

A portable memory store that:

  1. Auto-detects which agent is running (Claude, Copilot, Codex, Cursor…)
  2. Compresses your session into a structured, token-efficient summary using an LLM
  3. Stores it locally (SQLite) or in the cloud (Supabase, S3/R2, Firebase)
  4. Injects it automatically at the start of your next session in any agent

Install

pip install ai-agent-portable-memory

Then install hooks and set one API key — that's it:

memory install                        # hooks every agent on this machine

export ANTHROPIC_API_KEY=sk-ant-...   # Claude / Sonnet (auto-detected)
# OR
export OPENAI_API_KEY=sk-...          # GPT models
# OR
export GROQ_API_KEY=gsk_...           # Groq (free tier)
# Ollama needs no key — runs locally

Restart your AI agent. Memory is now live for all agents automatically.

For cloud storage backends:

pip install "ai-agent-portable-memory[supabase]"   # Supabase
pip install "ai-agent-portable-memory[s3]"         # AWS S3 or Cloudflare R2
pip install "ai-agent-portable-memory[firebase]"   # Firebase Firestore
pip install "ai-agent-portable-memory[all]"        # Everything

Quick Start

1. Install hooks and set one API key

memory install

export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY / GROQ_API_KEY / etc.

Restart your AI agent. That's it — sessions are now saved and restored automatically for every supported agent (Claude Code, Copilot CLI, Codex, Cursor, Windsurf).

2. Save a session manually (optional)

memory save

Paste your chat transcript, press Ctrl+D. The LLM compresses it into a structured summary, your editor opens for review, and it's saved.

3. List your sessions

memory list
╭────┬──────────┬──────────────────────────────────┬───────────┬──────────────────╮
│ #  │ ID       │ Title                            │ Project   │ Updated          │
├────┼──────────┼──────────────────────────────────┼───────────┼──────────────────┤
│ 1  │ a3f2c1b0 │ JWT Auth Middleware — halfway     │ ecommerce │ 2026-11-18 14:30 │
│ 2  │ 9e1d4a72 │ PostgreSQL schema design         │ ecommerce │ 2026-11-17 09:15 │
│ 3  │ 7c8b3f91 │ React dashboard setup            │ dashboard │ 2026-11-16 18:00 │
╰────┴──────────┴──────────────────────────────────┴───────────┴──────────────────╯

4. Load context into any AI

memory load 1          # by list number
memory load a3f2c1b0   # by ID prefix
memory load 1 --copy   # copy to clipboard

Paste the output at the start of your new AI chat. The AI instantly knows where you left off.


What a session summary looks like

## Title
JWT Auth Middleware — halfway through refresh token rotation

## Project
ecommerce

## What we were doing
Building JWT authentication for a React + Node.js e-commerce app.

## What was completed
- Login page UI (src/pages/Login.tsx)
- JWT token generation on backend (src/auth/jwt.js)
- httpOnly cookie setup on login endpoint

## Key decisions made
- httpOnly cookies instead of localStorage — XSS protection
- Access token TTL: 15min, Refresh token TTL: 7 days
- Library: jsonwebtoken v9

## Current state / where we stopped
Halfway through refresh token rotation middleware.
File: src/middleware/refreshToken.js — function written, error handling missing.

## Next steps
1. Finish error handling in refreshToken.js
2. Add protected route wrapper component
3. Test full auth flow with Postman

## Important context
- Backend: Express.js on port 3001
- Frontend: React + Vite on port 5173
- DB: PostgreSQL with Prisma ORM
- Auth route prefix: /api/auth

## Tags
react, nodejs, jwt, auth, express, postgresql

Compact. Structured. Ready to paste.


Configuration

Create a .env file or set environment variables:

# Storage backend (default: sqlite)
MEMORY_BACKEND=sqlite

# LLM provider for compression (default: openai)
MEMORY_LLM_PROVIDER=openai

# LLM API keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...

Storage Backends

SQLite (default — no setup required)

MEMORY_BACKEND=sqlite
SQLITE_DB_PATH=~/.ai-memory/memory.db   # optional, this is the default

Supabase

MEMORY_BACKEND=supabase
SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_KEY=your-anon-key

Run this SQL in your Supabase project:

CREATE TABLE sessions (
    id          TEXT PRIMARY KEY,
    project     TEXT NOT NULL DEFAULT 'default',
    title       TEXT NOT NULL,
    summary     TEXT NOT NULL,
    tags        JSONB NOT NULL DEFAULT '[]',
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX ON sessions USING GIN (to_tsvector('english', title || ' ' || summary));

Cloudflare R2 / AWS S3

MEMORY_BACKEND=s3
S3_BUCKET_NAME=my-memory-bucket
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...

# For Cloudflare R2 (add this):
S3_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com

Firebase Firestore

MEMORY_BACKEND=firebase
FIREBASE_CREDENTIALS_PATH=./serviceAccountKey.json
FIREBASE_PROJECT_ID=my-firebase-project

Auto-Save Claude Code Sessions (Optional)

Run once after installing:

memory setup --claude-hook       # save on session exit
memory setup --compact-hook      # save on context compaction (recommended)

--claude-hook saves when you exit Claude Code.

--compact-hook saves automatically whenever Claude Code compacts the context (when the conversation gets long). This acts as a natural mid-session checkpoint — you never lose progress even in very long sessions.

Use both together for full coverage:

memory setup --claude-hook
memory setup --compact-hook

To disable:

memory setup --remove-claude-hook
memory setup --remove-compact-hook

Save from Any AI Tool

memory save                          Paste transcript manually
memory save --from-claude            Auto-read last Claude Code session
memory save --from-chatgpt           Auto-read ChatGPT export (conversations.json)
memory save --from-cursor            Auto-read last Cursor session
memory save --from-windsurf          Auto-read last Windsurf session
memory save --from-file chat.txt     Read from any plain text or JSON file
memory save --from-claude --session <id>  Specific session by ID

CLI Reference

memory list                      List all sessions
memory list --project myapp      Filter by project

memory load <id>                 Print session context
memory load <id> --copy          Copy context to clipboard

memory save                      Save new session (paste transcript)
memory save --provider anthropic Use a specific LLM provider
memory save --project myapp      Set project name
memory save --no-edit            Skip editor review

memory search <query>            Search sessions by keyword
memory search auth --project api Filter search by project

memory delete <id>               Delete a session

memory setup --claude-hook         Auto-save on session exit
memory setup --compact-hook        Auto-save on context compaction
memory setup --remove-claude-hook  Disable exit auto-save
memory setup --remove-compact-hook Disable compaction auto-save

memory config                    Show current configuration

How it works

Your chat  →  memory save  →  LLM compresses  →  You review  →  Stored
                                                                    ↓
New AI chat  ←  paste  ←  memory load  ←  compact summary  ←  Retrieved

Contributing

PRs welcome. To add a new storage backend, implement the BaseBackend interface in memory/backends/base.py.

License

MIT


Codex support

Codex support is available alongside the existing Claude Code integration:

memory codex setup                       # install Codex save/load hooks
memory codex save --no-edit               # save this workspace's latest Codex session
memory codex load                         # load this project's latest context
memory codex checkpoint --summary-file memory-summary.md  # store a Codex-written summary

From the source checkout, use python3 -m memory in place of memory. After setup, restart Codex and review and trust the hooks using /hooks. See CODEX.md for project-scoped setup, direct checkpoints without an extra API call, removal, and environments where local hooks are unavailable.


GitHub Copilot CLI support

GitHub Copilot CLI support is available as a separate additive integration:

memory copilot setup                     # install hooks in ~/.copilot/settings.json (user scope)
memory copilot setup --project-local     # install hooks in ./.claude/settings.json (project scope)
memory copilot load                      # load this project's latest context
memory copilot save                      # save manually
memory copilot checkpoint --summary-file memory-summary.md  # store a Copilot-written summary directly
memory copilot setup --remove            # remove hooks

Hooks use Copilot CLI's SessionStart and Stop events:

  • SessionStart — injects the latest project memory as additional context at the start of each session.
  • Stop — saves a session checkpoint whenever the agent stops.

For project-scoped setup (checked into the repo), use --project-local. This writes to .claude/settings.json, which Copilot CLI reads automatically.

From the source checkout, use python3 -m memory in place of memory.

Metadata

Release files for ai-agent-portable-memory 0.1.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ai-agent-portable-memory 0.1.6
File Size Uploaded Provenance Actions
ai_agent_portable_memory-0.1.6.tar.gz 44.3 kB Without provenance Details for ai_agent_portable_memory-0.1.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ai-agent-portable-memory 0.1.6
File Interpreter ABI Platform Actions
ai_agent_portable_memory-0.1.6-py3-none-any.whl Python 3 none any Details for ai_agent_portable_memory-0.1.6-py3-none-any.whl

Total release size: 91.0 kB

Release files / ai_agent_portable_memory-0.1.6.tar.gz

Download URL ai_agent_portable_memory-0.1.6.tar.gz
Size 44.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a4ca93a07844d158b9db07085cbe8cf78bc82dda6ea320c1f4eabfdaacd2e8ab
BLAKE2b-256 checksum
How to use checksums
d61bbc0c25c8f217f0c35c61ce10a46d23ebf3eaab7050e6f306ab6622b85fb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Release files / ai_agent_portable_memory-0.1.6-py3-none-any.whl

Download URL ai_agent_portable_memory-0.1.6-py3-none-any.whl
Size 46.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
39f90a6f033324c5fddc8944e82f53707a745ff0bac27da0f3062951af2488bf
BLAKE2b-256 checksum
How to use checksums
7dfadffeee01b333370797fe2b635c58946b36c014278d8aa4bc63ecbe0f447d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.18

Security for ai-agent-portable-memory 0.1.6

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page