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:
- Auto-detects which agent is running (Claude, Copilot, Codex, Cursor…)
- Compresses your session into a structured, token-efficient summary using an LLM
- Stores it locally (SQLite) or in the cloud (Supabase, S3/R2, Firebase)
- 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.