ai-agent-portable-memory 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,281 @@
1
+ Metadata-Version: 2.4
2
+ Name: ai-agent-portable-memory
3
+ Version: 0.1.0
4
+ Summary: Portable compressed memory for AI agents — works with any LLM
5
+ License: MIT
6
+ Keywords: ai,memory,llm,chatgpt,claude,portable
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: click>=8.1
10
+ Requires-Dist: rich>=13.0
11
+ Requires-Dist: openai>=1.0
12
+ Requires-Dist: anthropic>=0.25
13
+ Requires-Dist: python-dotenv>=1.0
14
+ Provides-Extra: supabase
15
+ Requires-Dist: supabase>=2.0; extra == "supabase"
16
+ Provides-Extra: s3
17
+ Requires-Dist: boto3>=1.34; extra == "s3"
18
+ Provides-Extra: firebase
19
+ Requires-Dist: firebase-admin>=6.0; extra == "firebase"
20
+ Provides-Extra: all
21
+ Requires-Dist: supabase>=2.0; extra == "all"
22
+ Requires-Dist: boto3>=1.34; extra == "all"
23
+ Requires-Dist: firebase-admin>=6.0; extra == "all"
24
+
25
+ # AI Agent Portable Memory
26
+
27
+ > Carry your context across any AI — ChatGPT, Claude, Gemini, Grok, or any LLM.
28
+
29
+ Instead of losing your work every time you switch AI tools or start a new chat, **AI Agent Portable Memory** lets you save compact, structured session summaries and load them instantly into any AI conversation.
30
+
31
+ ---
32
+
33
+ ## The Problem
34
+
35
+ Every AI session starts blank. You lose:
36
+ - What you were building
37
+ - Decisions you already made
38
+ - Where you stopped
39
+
40
+ Copy-pasting raw chat logs wastes too many context tokens and is unmanageable.
41
+
42
+ ## The Solution
43
+
44
+ A portable memory store that:
45
+ 1. **Compresses** your session into a structured, token-efficient summary using an LLM
46
+ 2. **Lets you review and edit** the summary before saving
47
+ 3. **Stores it** locally (SQLite) or in the cloud (Supabase, S3/R2, Firebase)
48
+ 4. **Loads it** as a clean context block you paste into any AI
49
+
50
+ ---
51
+
52
+ ## Install
53
+
54
+ ```bash
55
+ pip install ai-agent-portable-memory
56
+ ```
57
+
58
+ Or from source:
59
+
60
+ ```bash
61
+ git clone https://github.com/your-username/AI-Agent-Portable-Memory
62
+ cd AI-Agent-Portable-Memory
63
+ pip install -e .
64
+ ```
65
+
66
+ For cloud storage backends:
67
+
68
+ ```bash
69
+ pip install "ai-agent-portable-memory[supabase]" # Supabase
70
+ pip install "ai-agent-portable-memory[s3]" # AWS S3 or Cloudflare R2
71
+ pip install "ai-agent-portable-memory[firebase]" # Firebase Firestore
72
+ pip install "ai-agent-portable-memory[all]" # Everything
73
+ ```
74
+
75
+ ---
76
+
77
+ ## Quick Start
78
+
79
+ ### 1. Set your LLM API key
80
+
81
+ ```bash
82
+ export OPENAI_API_KEY=sk-... # OpenAI (default)
83
+ # or
84
+ export ANTHROPIC_API_KEY=sk-ant-... # Claude
85
+ # or
86
+ export GROQ_API_KEY=gsk_... # Groq (free tier available)
87
+ ```
88
+
89
+ ### 2. Save a session
90
+
91
+ ```bash
92
+ memory save
93
+ ```
94
+
95
+ Paste your chat transcript, press `Ctrl+D`. The LLM compresses it into a structured summary, your editor opens for review, and it's saved.
96
+
97
+ ### 3. List your sessions
98
+
99
+ ```bash
100
+ memory list
101
+ ```
102
+
103
+ ```
104
+ ╭────┬──────────┬──────────────────────────────────┬───────────┬──────────────────╮
105
+ │ # │ ID │ Title │ Project │ Updated │
106
+ ├────┼──────────┼──────────────────────────────────┼───────────┼──────────────────┤
107
+ │ 1 │ a3f2c1b0 │ JWT Auth Middleware — halfway │ ecommerce │ 2026-11-18 14:30 │
108
+ │ 2 │ 9e1d4a72 │ PostgreSQL schema design │ ecommerce │ 2026-11-17 09:15 │
109
+ │ 3 │ 7c8b3f91 │ React dashboard setup │ dashboard │ 2026-11-16 18:00 │
110
+ ╰────┴──────────┴──────────────────────────────────┴───────────┴──────────────────╯
111
+ ```
112
+
113
+ ### 4. Load context into any AI
114
+
115
+ ```bash
116
+ memory load 1 # by list number
117
+ memory load a3f2c1b0 # by ID prefix
118
+ memory load 1 --copy # copy to clipboard
119
+ ```
120
+
121
+ Paste the output at the start of your new AI chat. The AI instantly knows where you left off.
122
+
123
+ ---
124
+
125
+ ## What a session summary looks like
126
+
127
+ ```markdown
128
+ ## Title
129
+ JWT Auth Middleware — halfway through refresh token rotation
130
+
131
+ ## Project
132
+ ecommerce
133
+
134
+ ## What we were doing
135
+ Building JWT authentication for a React + Node.js e-commerce app.
136
+
137
+ ## What was completed
138
+ - Login page UI (src/pages/Login.tsx)
139
+ - JWT token generation on backend (src/auth/jwt.js)
140
+ - httpOnly cookie setup on login endpoint
141
+
142
+ ## Key decisions made
143
+ - httpOnly cookies instead of localStorage — XSS protection
144
+ - Access token TTL: 15min, Refresh token TTL: 7 days
145
+ - Library: jsonwebtoken v9
146
+
147
+ ## Current state / where we stopped
148
+ Halfway through refresh token rotation middleware.
149
+ File: src/middleware/refreshToken.js — function written, error handling missing.
150
+
151
+ ## Next steps
152
+ 1. Finish error handling in refreshToken.js
153
+ 2. Add protected route wrapper component
154
+ 3. Test full auth flow with Postman
155
+
156
+ ## Important context
157
+ - Backend: Express.js on port 3001
158
+ - Frontend: React + Vite on port 5173
159
+ - DB: PostgreSQL with Prisma ORM
160
+ - Auth route prefix: /api/auth
161
+
162
+ ## Tags
163
+ react, nodejs, jwt, auth, express, postgresql
164
+ ```
165
+
166
+ **Compact. Structured. Ready to paste.**
167
+
168
+ ---
169
+
170
+ ## Configuration
171
+
172
+ Create a `.env` file or set environment variables:
173
+
174
+ ```env
175
+ # Storage backend (default: sqlite)
176
+ MEMORY_BACKEND=sqlite
177
+
178
+ # LLM provider for compression (default: openai)
179
+ MEMORY_LLM_PROVIDER=openai
180
+
181
+ # LLM API keys
182
+ OPENAI_API_KEY=sk-...
183
+ ANTHROPIC_API_KEY=sk-ant-...
184
+ GROQ_API_KEY=gsk_...
185
+ ```
186
+
187
+ ### Storage Backends
188
+
189
+ #### SQLite (default — no setup required)
190
+
191
+ ```env
192
+ MEMORY_BACKEND=sqlite
193
+ SQLITE_DB_PATH=~/.ai-memory/memory.db # optional, this is the default
194
+ ```
195
+
196
+ #### Supabase
197
+
198
+ ```env
199
+ MEMORY_BACKEND=supabase
200
+ SUPABASE_URL=https://xxxxx.supabase.co
201
+ SUPABASE_KEY=your-anon-key
202
+ ```
203
+
204
+ Run this SQL in your Supabase project:
205
+
206
+ ```sql
207
+ CREATE TABLE sessions (
208
+ id TEXT PRIMARY KEY,
209
+ project TEXT NOT NULL DEFAULT 'default',
210
+ title TEXT NOT NULL,
211
+ summary TEXT NOT NULL,
212
+ tags JSONB NOT NULL DEFAULT '[]',
213
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
214
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
215
+ );
216
+ CREATE INDEX ON sessions USING GIN (to_tsvector('english', title || ' ' || summary));
217
+ ```
218
+
219
+ #### Cloudflare R2 / AWS S3
220
+
221
+ ```env
222
+ MEMORY_BACKEND=s3
223
+ S3_BUCKET_NAME=my-memory-bucket
224
+ AWS_ACCESS_KEY_ID=...
225
+ AWS_SECRET_ACCESS_KEY=...
226
+
227
+ # For Cloudflare R2 (add this):
228
+ S3_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
229
+ ```
230
+
231
+ #### Firebase Firestore
232
+
233
+ ```env
234
+ MEMORY_BACKEND=firebase
235
+ FIREBASE_CREDENTIALS_PATH=./serviceAccountKey.json
236
+ FIREBASE_PROJECT_ID=my-firebase-project
237
+ ```
238
+
239
+ ---
240
+
241
+ ## CLI Reference
242
+
243
+ ```
244
+ memory list List all sessions
245
+ memory list --project myapp Filter by project
246
+
247
+ memory load <id> Print session context
248
+ memory load <id> --copy Copy context to clipboard
249
+
250
+ memory save Save new session (paste transcript)
251
+ memory save --provider anthropic Use a specific LLM provider
252
+ memory save --project myapp Set project name
253
+ memory save --no-edit Skip editor review
254
+
255
+ memory search <query> Search sessions by keyword
256
+ memory search auth --project api Filter search by project
257
+
258
+ memory delete <id> Delete a session
259
+
260
+ memory config Show current configuration
261
+ ```
262
+
263
+ ---
264
+
265
+ ## How it works
266
+
267
+ ```
268
+ Your chat → memory save → LLM compresses → You review → Stored
269
+ ↓
270
+ New AI chat ← paste ← memory load ← compact summary ← Retrieved
271
+ ```
272
+
273
+ ---
274
+
275
+ ## Contributing
276
+
277
+ PRs welcome. To add a new storage backend, implement the `BaseBackend` interface in `memory/backends/base.py`.
278
+
279
+ ## License
280
+
281
+ MIT
@@ -0,0 +1,257 @@
1
+ # AI Agent Portable Memory
2
+
3
+ > Carry your context across any AI — ChatGPT, Claude, Gemini, Grok, or any LLM.
4
+
5
+ Instead of losing your work every time you switch AI tools or start a new chat, **AI Agent Portable Memory** lets you save compact, structured session summaries and load them instantly into any AI conversation.
6
+
7
+ ---
8
+
9
+ ## The Problem
10
+
11
+ Every AI session starts blank. You lose:
12
+ - What you were building
13
+ - Decisions you already made
14
+ - Where you stopped
15
+
16
+ Copy-pasting raw chat logs wastes too many context tokens and is unmanageable.
17
+
18
+ ## The Solution
19
+
20
+ A portable memory store that:
21
+ 1. **Compresses** your session into a structured, token-efficient summary using an LLM
22
+ 2. **Lets you review and edit** the summary before saving
23
+ 3. **Stores it** locally (SQLite) or in the cloud (Supabase, S3/R2, Firebase)
24
+ 4. **Loads it** as a clean context block you paste into any AI
25
+
26
+ ---
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install ai-agent-portable-memory
32
+ ```
33
+
34
+ Or from source:
35
+
36
+ ```bash
37
+ git clone https://github.com/your-username/AI-Agent-Portable-Memory
38
+ cd AI-Agent-Portable-Memory
39
+ pip install -e .
40
+ ```
41
+
42
+ For cloud storage backends:
43
+
44
+ ```bash
45
+ pip install "ai-agent-portable-memory[supabase]" # Supabase
46
+ pip install "ai-agent-portable-memory[s3]" # AWS S3 or Cloudflare R2
47
+ pip install "ai-agent-portable-memory[firebase]" # Firebase Firestore
48
+ pip install "ai-agent-portable-memory[all]" # Everything
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Quick Start
54
+
55
+ ### 1. Set your LLM API key
56
+
57
+ ```bash
58
+ export OPENAI_API_KEY=sk-... # OpenAI (default)
59
+ # or
60
+ export ANTHROPIC_API_KEY=sk-ant-... # Claude
61
+ # or
62
+ export GROQ_API_KEY=gsk_... # Groq (free tier available)
63
+ ```
64
+
65
+ ### 2. Save a session
66
+
67
+ ```bash
68
+ memory save
69
+ ```
70
+
71
+ Paste your chat transcript, press `Ctrl+D`. The LLM compresses it into a structured summary, your editor opens for review, and it's saved.
72
+
73
+ ### 3. List your sessions
74
+
75
+ ```bash
76
+ memory list
77
+ ```
78
+
79
+ ```
80
+ ╭────┬──────────┬──────────────────────────────────┬───────────┬──────────────────╮
81
+ │ # │ ID │ Title │ Project │ Updated │
82
+ ├────┼──────────┼──────────────────────────────────┼───────────┼──────────────────┤
83
+ │ 1 │ a3f2c1b0 │ JWT Auth Middleware — halfway │ ecommerce │ 2026-11-18 14:30 │
84
+ │ 2 │ 9e1d4a72 │ PostgreSQL schema design │ ecommerce │ 2026-11-17 09:15 │
85
+ │ 3 │ 7c8b3f91 │ React dashboard setup │ dashboard │ 2026-11-16 18:00 │
86
+ ╰────┴──────────┴──────────────────────────────────┴───────────┴──────────────────╯
87
+ ```
88
+
89
+ ### 4. Load context into any AI
90
+
91
+ ```bash
92
+ memory load 1 # by list number
93
+ memory load a3f2c1b0 # by ID prefix
94
+ memory load 1 --copy # copy to clipboard
95
+ ```
96
+
97
+ Paste the output at the start of your new AI chat. The AI instantly knows where you left off.
98
+
99
+ ---
100
+
101
+ ## What a session summary looks like
102
+
103
+ ```markdown
104
+ ## Title
105
+ JWT Auth Middleware — halfway through refresh token rotation
106
+
107
+ ## Project
108
+ ecommerce
109
+
110
+ ## What we were doing
111
+ Building JWT authentication for a React + Node.js e-commerce app.
112
+
113
+ ## What was completed
114
+ - Login page UI (src/pages/Login.tsx)
115
+ - JWT token generation on backend (src/auth/jwt.js)
116
+ - httpOnly cookie setup on login endpoint
117
+
118
+ ## Key decisions made
119
+ - httpOnly cookies instead of localStorage — XSS protection
120
+ - Access token TTL: 15min, Refresh token TTL: 7 days
121
+ - Library: jsonwebtoken v9
122
+
123
+ ## Current state / where we stopped
124
+ Halfway through refresh token rotation middleware.
125
+ File: src/middleware/refreshToken.js — function written, error handling missing.
126
+
127
+ ## Next steps
128
+ 1. Finish error handling in refreshToken.js
129
+ 2. Add protected route wrapper component
130
+ 3. Test full auth flow with Postman
131
+
132
+ ## Important context
133
+ - Backend: Express.js on port 3001
134
+ - Frontend: React + Vite on port 5173
135
+ - DB: PostgreSQL with Prisma ORM
136
+ - Auth route prefix: /api/auth
137
+
138
+ ## Tags
139
+ react, nodejs, jwt, auth, express, postgresql
140
+ ```
141
+
142
+ **Compact. Structured. Ready to paste.**
143
+
144
+ ---
145
+
146
+ ## Configuration
147
+
148
+ Create a `.env` file or set environment variables:
149
+
150
+ ```env
151
+ # Storage backend (default: sqlite)
152
+ MEMORY_BACKEND=sqlite
153
+
154
+ # LLM provider for compression (default: openai)
155
+ MEMORY_LLM_PROVIDER=openai
156
+
157
+ # LLM API keys
158
+ OPENAI_API_KEY=sk-...
159
+ ANTHROPIC_API_KEY=sk-ant-...
160
+ GROQ_API_KEY=gsk_...
161
+ ```
162
+
163
+ ### Storage Backends
164
+
165
+ #### SQLite (default — no setup required)
166
+
167
+ ```env
168
+ MEMORY_BACKEND=sqlite
169
+ SQLITE_DB_PATH=~/.ai-memory/memory.db # optional, this is the default
170
+ ```
171
+
172
+ #### Supabase
173
+
174
+ ```env
175
+ MEMORY_BACKEND=supabase
176
+ SUPABASE_URL=https://xxxxx.supabase.co
177
+ SUPABASE_KEY=your-anon-key
178
+ ```
179
+
180
+ Run this SQL in your Supabase project:
181
+
182
+ ```sql
183
+ CREATE TABLE sessions (
184
+ id TEXT PRIMARY KEY,
185
+ project TEXT NOT NULL DEFAULT 'default',
186
+ title TEXT NOT NULL,
187
+ summary TEXT NOT NULL,
188
+ tags JSONB NOT NULL DEFAULT '[]',
189
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
190
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
191
+ );
192
+ CREATE INDEX ON sessions USING GIN (to_tsvector('english', title || ' ' || summary));
193
+ ```
194
+
195
+ #### Cloudflare R2 / AWS S3
196
+
197
+ ```env
198
+ MEMORY_BACKEND=s3
199
+ S3_BUCKET_NAME=my-memory-bucket
200
+ AWS_ACCESS_KEY_ID=...
201
+ AWS_SECRET_ACCESS_KEY=...
202
+
203
+ # For Cloudflare R2 (add this):
204
+ S3_ENDPOINT_URL=https://<account_id>.r2.cloudflarestorage.com
205
+ ```
206
+
207
+ #### Firebase Firestore
208
+
209
+ ```env
210
+ MEMORY_BACKEND=firebase
211
+ FIREBASE_CREDENTIALS_PATH=./serviceAccountKey.json
212
+ FIREBASE_PROJECT_ID=my-firebase-project
213
+ ```
214
+
215
+ ---
216
+
217
+ ## CLI Reference
218
+
219
+ ```
220
+ memory list List all sessions
221
+ memory list --project myapp Filter by project
222
+
223
+ memory load <id> Print session context
224
+ memory load <id> --copy Copy context to clipboard
225
+
226
+ memory save Save new session (paste transcript)
227
+ memory save --provider anthropic Use a specific LLM provider
228
+ memory save --project myapp Set project name
229
+ memory save --no-edit Skip editor review
230
+
231
+ memory search <query> Search sessions by keyword
232
+ memory search auth --project api Filter search by project
233
+
234
+ memory delete <id> Delete a session
235
+
236
+ memory config Show current configuration
237
+ ```
238
+
239
+ ---
240
+
241
+ ## How it works
242
+
243
+ ```
244
+ Your chat → memory save → LLM compresses → You review → Stored
245
+ ↓
246
+ New AI chat ← paste ← memory load ← compact summary ← Retrieved
247
+ ```
248
+
249
+ ---
250
+
251
+ ## Contributing
252
+
253
+ PRs welcome. To add a new storage backend, implement the `BaseBackend` interface in `memory/backends/base.py`.
254
+
255
+ ## License
256
+
257
+ MIT