Yash030 commited on
Commit
7c69c77
·
1 Parent(s): e0e2e6c

fix: Readme ref links are fixed

Browse files
CONTRIBUTING.md CHANGED
@@ -8,7 +8,7 @@ Apache-2.0. Every contribution is covered by it.
8
 
9
  ## Before opening an issue
10
 
11
- Search [open issues](https://github.com/Yash030/agentmemory-python/issues?q=is%3Aopen) and [closed issues](https://github.com/Yash030/agentmemory-python/issues?q=is%3Aclosed) first.
12
 
13
  **Bug reports** — include:
14
  - Python version (`python --version`)
 
8
 
9
  ## Before opening an issue
10
 
11
+ Search [open issues](https://github.com/Yashwant00CR7/agentcache/issues?q=is%3Aopen) and [closed issues](https://github.com/Yashwant00CR7/agentcache/issues?q=is%3Aclosed) first.
12
 
13
  **Bug reports** — include:
14
  - Python version (`python --version`)
INSTALL_FOR_AGENTS.md CHANGED
@@ -17,8 +17,8 @@ Default mode works with no API key. It runs BM25 keyword search out of the box.
17
  ## 1. Clone the repo
18
 
19
  ```bash
20
- git clone https://github.com/Yash030/agentcache-python.git
21
- cd agentcache-python
22
  ```
23
 
24
  Expect: the directory exists with `src/app.py` inside.
 
17
  ## 1. Clone the repo
18
 
19
  ```bash
20
+ git clone https://github.com/Yashwant00CR7/agentcache.git
21
+ cd agentcache
22
  ```
23
 
24
  Expect: the directory exists with `src/app.py` inside.
README.md CHANGED
@@ -14,18 +14,6 @@ pinned: false
14
  Works with Claude Code, Cursor, Cline, Windsurf, Gemini CLI, and any MCP client.
15
  </p>
16
 
17
- <p align="center">
18
- <a href="README.md">English</a> |
19
- <a href="READMEs/README.zh-CN.md">简体中文</a> |
20
- <a href="READMEs/README.ja-JP.md">日本語</a> |
21
- <a href="READMEs/README.ko-KR.md">한국어</a> |
22
- <a href="READMEs/README.es-ES.md">Español</a> |
23
- <a href="READMEs/README.hi-IN.md">हिन्दी</a> |
24
- <a href="READMEs/README.pt-BR.md">Português</a> |
25
- <a href="READMEs/README.fr-FR.md">Français</a> |
26
- <a href="READMEs/README.de-DE.md">Deutsch</a>
27
- </p>
28
-
29
  <p align="center">
30
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
31
  <img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL" />
@@ -68,8 +56,8 @@ Your agent captures every tool call, stores them as observations, compresses the
68
 
69
  ```bash
70
  # Clone
71
- git clone https://github.com/Yash030/agentcache-python.git
72
- cd agentcache-python
73
 
74
  # Install dependencies (no build step)
75
  pip install -r requirements.txt
 
14
  Works with Claude Code, Cursor, Cline, Windsurf, Gemini CLI, and any MCP client.
15
  </p>
16
 
 
 
 
 
 
 
 
 
 
 
 
 
17
  <p align="center">
18
  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
19
  <img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL" />
 
56
 
57
  ```bash
58
  # Clone
59
+ git clone https://github.com/Yashwant00CR7/agentcache.git
60
+ cd agentcache
61
 
62
  # Install dependencies (no build step)
63
  pip install -r requirements.txt
agentcache.egg-info/PKG-INFO ADDED
@@ -0,0 +1,515 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Metadata-Version: 2.4
2
+ Name: agentcache
3
+ Version: 0.9.8
4
+ Summary: A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite
5
+ License: MIT
6
+ Requires-Python: >=3.10
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: flask>=3.0.0
10
+ Requires-Dist: flask-sock>=0.7.0
11
+ Requires-Dist: requests>=2.31.0
12
+ Requires-Dist: python-dateutil>=2.8.2
13
+ Requires-Dist: huggingface_hub>=0.20.0
14
+ Requires-Dist: websockets>=12.0
15
+ Provides-Extra: dev
16
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
17
+ Requires-Dist: hypothesis>=6.100.0; extra == "dev"
18
+ Provides-Extra: local-embeddings
19
+ Requires-Dist: sentence-transformers>=2.7.0; extra == "local-embeddings"
20
+ Dynamic: license-file
21
+
22
+ ---
23
+ title: AgentCache Python
24
+ emoji: 🧠
25
+ colorFrom: blue
26
+ colorTo: indigo
27
+ sdk: docker
28
+ pinned: false
29
+ ---
30
+
31
+ <h1 align="center">agentcache-python</h1>
32
+
33
+ <p align="center">
34
+ <strong>Persistent memory for AI coding agents — pure Python, zero external databases.</strong><br/>
35
+ Works with Claude Code, Cursor, Cline, Windsurf, Gemini CLI, and any MCP client.
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="README.md">English</a> |
40
+ <a href="READMEs/README.zh-CN.md">简体中文</a> |
41
+ <a href="READMEs/README.ja-JP.md">日本語</a> |
42
+ <a href="READMEs/README.ko-KR.md">한국어</a> |
43
+ <a href="READMEs/README.es-ES.md">Español</a> |
44
+ <a href="READMEs/README.hi-IN.md">हिन्दी</a> |
45
+ <a href="READMEs/README.pt-BR.md">Português</a> |
46
+ <a href="READMEs/README.fr-FR.md">Français</a> |
47
+ <a href="READMEs/README.de-DE.md">Deutsch</a>
48
+ </p>
49
+
50
+ <p align="center">
51
+ <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
52
+ <img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL" />
53
+ <img src="https://img.shields.io/badge/Flask-3.0-000000?style=for-the-badge&logo=flask&logoColor=white" alt="Flask 3.0" />
54
+ <img src="https://img.shields.io/badge/MCP-Compatible-6B21A8?style=for-the-badge" alt="MCP Compatible" />
55
+ <img src="https://img.shields.io/badge/HuggingFace-Space-FF9D00?style=for-the-badge&logo=huggingface&logoColor=white" alt="HuggingFace Space" />
56
+ </p>
57
+
58
+ <p align="center">
59
+ <a href="#quick-start">Quick Start</a> &bull;
60
+ <a href="#features">Features</a> &bull;
61
+ <a href="#mcp-integration">MCP</a> &bull;
62
+ <a href="#api-reference">API</a> &bull;
63
+ <a href="#configuration">Config</a> &bull;
64
+ <a href="#deploy-to-huggingface">Deploy</a> &bull;
65
+ <a href="#viewer">Viewer</a> &bull;
66
+ <a href="#architecture">Architecture</a>
67
+ </p>
68
+
69
+ ---
70
+
71
+ ## What Is This?
72
+
73
+ **agentcache-python** is a Python reimplementation of the [agentcache](https://github.com/rohitg00/agentcache) persistent memory server. It exposes a REST API, WebSocket stream, and MCP tools endpoint that AI coding agents use to store and retrieve session observations, long-term memories, lessons, and pinned memory slots.
74
+
75
+ Key differences from the Node.js original:
76
+
77
+ - **No Node.js or iii-engine** — runs with plain `python src/app.py`
78
+ - **SQLite instead of Dolt** — single file, WAL mode, instant startup
79
+ - **HuggingFace Space ready** — deploys in one click, data synced to an HF dataset repo
80
+ - **Same REST + MCP wire format** — drop-in for any agent already wired to agentcache
81
+
82
+ Your agent captures every tool call, stores them as observations, compresses them into searchable memory, and injects the right context at the start of every new session — automatically.
83
+
84
+ ---
85
+
86
+ ## Quick Start
87
+
88
+ ### Run locally
89
+
90
+ ```bash
91
+ # Clone
92
+ git clone https://github.com/Yash030/agentcache-python.git
93
+ cd agentcache-python
94
+
95
+ # Install dependencies (no build step)
96
+ pip install -r requirements.txt
97
+
98
+ # Start the server
99
+ python src/app.py
100
+ ```
101
+
102
+ Server starts on **http://localhost:3111**. Open the viewer at http://localhost:3111/viewer.
103
+
104
+ ### Verify it works
105
+
106
+ ```bash
107
+ # Health check
108
+ curl http://localhost:3111/agentcache/livez
109
+ # {"status": "ok"}
110
+
111
+ # Save a memory
112
+ curl -X POST http://localhost:3111/agentcache/remember \
113
+ -H "Content-Type: application/json" \
114
+ -d '{"content": "JWT auth uses jose middleware in src/middleware/auth.ts", "concepts": ["auth", "jwt"]}'
115
+
116
+ # Recall it
117
+ curl -X POST http://localhost:3111/agentcache/search \
118
+ -H "Content-Type: application/json" \
119
+ -d '{"query": "authentication middleware", "limit": 5}'
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Features
125
+
126
+ | Feature | Status | Notes |
127
+ |---------|--------|-------|
128
+ | REST API — sessions, memories, observations | ✅ | Full surface |
129
+ | WebSocket live stream | ✅ | `/stream/mem-live/viewer` |
130
+ | MCP tools endpoint | ✅ | 31 tools |
131
+ | Built-in HTML viewer | ✅ | Real-time dashboard at `/viewer` |
132
+ | BM25 keyword search | ✅ | Always on, no API key needed |
133
+ | Hybrid BM25 + vector search | ✅ | Requires `GEMINI_API_KEY` |
134
+ | 4-tier memory consolidation | ⚙️ | `CONSOLIDATION_ENABLED=true` + LLM key |
135
+ | Knowledge graph extraction | ⚙️ | `GRAPH_EXTRACTION_ENABLED=true` + LLM key |
136
+ | LLM observation compression | ⚙️ | `AGENTCACHE_AUTO_COMPRESS=true` + LLM key |
137
+ | Lessons with confidence decay | ✅ | Fingerprinted, auto-strengthen on repeat |
138
+ | Memory slots (pinned context) | ✅ | CRUD + auto-reflect |
139
+ | Session replay | ✅ | Full timeline in viewer |
140
+ | Audit log | ✅ | Tracks every write with agent_id + timestamp |
141
+ | HuggingFace Space deploy | ✅ | One-click, data synced to dataset repo |
142
+ | Privacy filtering | ✅ | Strips API keys, tokens before storage |
143
+
144
+ ### 4-Tier Memory Model
145
+
146
+ Inspired by how human memory works — raw experience → compressed episodes → extracted facts → learned patterns.
147
+
148
+ | Tier | What | When |
149
+ |------|------|------|
150
+ | **Working** | Raw observations from tool use | Every tool call |
151
+ | **Episodic** | Compressed session summaries | Session end |
152
+ | **Semantic** | Extracted facts and patterns | Consolidation |
153
+ | **Procedural** | Workflows and decision patterns | Consolidation |
154
+
155
+ ---
156
+
157
+ ## MCP Integration
158
+
159
+ Wire agentcache-python into your agent's MCP config. It speaks the same MCP protocol as the Node.js original.
160
+
161
+ ### Most agents (Cursor, Claude Desktop, Cline, Windsurf)
162
+
163
+ ```json
164
+ {
165
+ "mcpServers": {
166
+ "agentcache": {
167
+ "command": "npx",
168
+ "args": ["-y", "@agentcache/mcp"],
169
+ "env": {
170
+ "AGENTCACHE_URL": "http://localhost:3111"
171
+ }
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ ### Claude Code
178
+
179
+ Paste this prompt and your agent will wire everything:
180
+
181
+ ```
182
+ Start agentcache-python: run `python src/app.py` from the agentcache-python directory.
183
+ Then add this MCP server to ~/.claude.json under mcpServers:
184
+ {
185
+ "agentcache": {
186
+ "command": "npx",
187
+ "args": ["-y", "@agentcache/mcp"],
188
+ "env": { "AGENTCACHE_URL": "http://localhost:3111" }
189
+ }
190
+ }
191
+ Verify with: curl http://localhost:3111/agentcache/livez
192
+ Open the viewer at: http://localhost:3111/viewer
193
+ ```
194
+
195
+ ### Available MCP Tools (31)
196
+
197
+ | Tool | Description |
198
+ |------|-------------|
199
+ | `memory_save` | Save a long-term insight, decision, or pattern |
200
+ | `memory_recall` | Search past observations by keyword |
201
+ | `memory_smart_search` | Hybrid BM25 + vector semantic search |
202
+ | `memory_sessions` | List recent sessions |
203
+ | `memory_sessions_list` | Retrieve all memory sessions |
204
+ | `memory_timeline` | Chronological observations for a session |
205
+ | `memory_observations` | Observations for a session |
206
+ | `memory_profile` | Per-project concept + file profile |
207
+ | `memory_lessons` | List active lessons with confidence scores |
208
+ | `memory_lesson_save` | Save a lesson (duplicate saves strengthen it) |
209
+ | `memory_lesson_recall` | Search lessons by query |
210
+ | `memory_lesson_search` | Search lessons by keywords |
211
+ | `memory_consolidate` | Run 4-tier memory consolidation |
212
+ | `memory_reflect` | Reflect on session, update context |
213
+ | `memory_diagnose` | Health check across all subsystems |
214
+ | `memory_forget` | Delete memory, session, or observations |
215
+ | `memory_export` | Export all memory data as JSON |
216
+ | `agent_observe` | Log agent execution observation |
217
+ | `agent_remember` | Save agent cache to long-term storage |
218
+ | `memory_antigravity_sync` | Sync Antigravity transcripts to memory |
219
+ | `memory_antigravity_sync_all` | Master sync: transcript + crystallize + reflect |
220
+ | `memory_slot_list` | List all pinned memory slots |
221
+ | `memory_slot_get` | Retrieve a specific pinned memory slot |
222
+ | `memory_slot_create` | Create/overwrite a pinned memory slot |
223
+ | `memory_slot_append` | Append text content to a pinned memory slot |
224
+ | `memory_slot_replace` | Replace pinned memory slot content |
225
+ | `memory_slot_delete` | Delete a pinned memory slot |
226
+ | `memory_action_create` | Create a new work item / action |
227
+ | `memory_action_update` | Update fields of an existing action |
228
+ | `memory_frontier` | Get active and pending actions sorted by priority |
229
+ | `memory_crystallize` | Crystallize/summarize observations in a session |
230
+
231
+ ---
232
+
233
+ ## API Reference
234
+
235
+ Base URL: `http://localhost:3111/agentcache`
236
+
237
+ ### Health
238
+
239
+ | Method | Path | Description |
240
+ |--------|------|-------------|
241
+ | `GET` | `/livez` | Liveness probe — no auth required |
242
+
243
+ ### Sessions
244
+
245
+ | Method | Path | Description |
246
+ |--------|------|-------------|
247
+ | `POST` | `/session/start` | Start a new session |
248
+ | `POST` | `/session/end` | End a session |
249
+ | `POST` | `/session/commit` | Commit session with summary |
250
+ | `GET` | `/sessions` | List all sessions |
251
+
252
+ ### Observations
253
+
254
+ | Method | Path | Description |
255
+ |--------|------|-------------|
256
+ | `POST` | `/observe` | Ingest a hook event observation |
257
+ | `POST` | `/agent/observe` | Simplified observe for direct agent use |
258
+ | `GET` | `/observations` | List observations (`?session_id=`) |
259
+ | `POST` | `/timeline` | Chronological observation window |
260
+
261
+ ### Memories
262
+
263
+ | Method | Path | Description |
264
+ |--------|------|-------------|
265
+ | `POST` | `/remember` | Save long-term memory |
266
+ | `POST` | `/agent/remember` | Simplified remember |
267
+ | `POST` | `/forget` | Delete memory / session / observations |
268
+ | `POST` | `/search` | BM25 + vector search |
269
+ | `POST` | `/context` | Compile context for a session + project |
270
+ | `GET` | `/memories` | List memories (`?latest=true&limit=N`) |
271
+ | `POST` | `/evolve` | Create a new memory version |
272
+
273
+ ### Lessons
274
+
275
+ | Method | Path | Description |
276
+ |--------|------|-------------|
277
+ | `GET` | `/lessons` | List lessons |
278
+ | `POST` | `/lessons` | Create lesson |
279
+ | `POST` | `/lessons/search` | Search lessons |
280
+ | `POST` | `/lessons/strengthen` | Reinforce an existing lesson |
281
+
282
+ ### Slots
283
+
284
+ | Method | Path | Description |
285
+ |--------|------|-------------|
286
+ | `GET` | `/slots` | List all pinned slots |
287
+ | `POST` | `/slot` | Create or update a slot |
288
+ | `GET` | `/slot` | Get slot by name |
289
+ | `DELETE` | `/slot` | Delete a slot |
290
+ | `POST` | `/slot/reflect` | Auto-populate from session observations |
291
+
292
+ ### Graph + Profile
293
+
294
+ | Method | Path | Description |
295
+ |--------|------|-------------|
296
+ | `GET` | `/relations` | Knowledge graph edges |
297
+ | `POST` | `/relations` | Add a relation |
298
+ | `GET` | `/profile` | Project profile (top concepts, files) |
299
+
300
+ ### Actions
301
+
302
+ | Method | Path | Description |
303
+ |--------|------|-------------|
304
+ | `GET` | `/actions` | List actions |
305
+ | `POST` | `/actions` | Create an action |
306
+ | `PATCH` | `/actions/<id>` | Update action status / fields |
307
+ | `GET` | `/frontier` | Pending actions sorted by priority |
308
+ | `GET` | `/insights` | List insights |
309
+
310
+ ### Replay
311
+
312
+ | Method | Path | Description |
313
+ |--------|------|-------------|
314
+ | `GET` | `/replay/sessions` | Sessions list for replay tab |
315
+ | `GET` | `/replay/load` | Full session + observations (`?sessionId=`) |
316
+
317
+ ### MCP
318
+
319
+ | Method | Path | Description |
320
+ |--------|------|-------------|
321
+ | `GET` | `/mcp/tools` | MCP tool schema list |
322
+ | `POST` | `/mcp/tools` | MCP tool call dispatch |
323
+
324
+ ---
325
+
326
+ ## Configuration
327
+
328
+ Create `~/.agentcache/.env` (no `export` prefix needed):
329
+
330
+ ```env
331
+ # Server port
332
+ III_REST_PORT=3111
333
+
334
+ # Vector search — enables Gemini 768-dim embeddings
335
+ GEMINI_API_KEY=your-gemini-key
336
+
337
+ # LLM for compression / consolidation / graph extraction
338
+ # Any one of these enables LLM features:
339
+ ANTHROPIC_API_KEY=your-anthropic-key
340
+ # OPENAI_API_KEY=your-openai-key
341
+ # GEMINI_API_KEY=your-key (same key as above works for both)
342
+
343
+ # LLM-powered features (disabled by default — spend tokens)
344
+ CONSOLIDATION_ENABLED=true
345
+ GRAPH_EXTRACTION_ENABLED=true
346
+ AGENTCACHE_AUTO_COMPRESS=true
347
+
348
+ # Context injection limits
349
+ TOKEN_BUDGET=2000
350
+ MAX_OBS_PER_SESSION=500
351
+
352
+ # Auth — set to require Bearer token on all endpoints
353
+ AGENTCACHE_SECRET=your-secret
354
+
355
+ # Agent scope isolation
356
+ AGENT_ID=my-agent
357
+ AGENTCACHE_AGENT_SCOPE=isolated # only see this agent's data
358
+
359
+ # HuggingFace sync
360
+ HF_TOKEN=your-hf-token
361
+ AGENTCACHE_DATASET_REPO=username/agentcache-data
362
+ ```
363
+
364
+ ### Full Variable Reference
365
+
366
+ | Variable | Default | Purpose |
367
+ |----------|---------|---------|
368
+ | `III_REST_PORT` / `PORT` | `3111` | API server port |
369
+ | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search |
370
+ | `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
371
+ | `AGENT_ID` | — | Default agent ID for scope isolation |
372
+ | `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filters data to current `AGENT_ID` |
373
+ | `MAX_OBS_PER_SESSION` | `500` | Hard cap on observations per session |
374
+ | `TOKEN_BUDGET` | `2000` | Max tokens in compiled context |
375
+ | `GRAPH_EXTRACTION_ENABLED` | `false` | Knowledge graph (needs LLM) |
376
+ | `CONSOLIDATION_ENABLED` | `false` | Memory consolidation (needs LLM) |
377
+ | `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM observation compression |
378
+
379
+ ---
380
+
381
+ ## Viewer
382
+
383
+ Built-in dashboard at **http://localhost:3111/viewer**.
384
+
385
+ | Tab | What You See |
386
+ |-----|-------------|
387
+ | **Dashboard** | Session stats, memory counts, recent activity |
388
+ | **Sessions** | Browse sessions, inspect observations |
389
+ | **Memories** | Search, filter, and read long-term memories |
390
+ | **Graph** | Project folder visualization — nodes = folders, edges = shared concepts or parent path |
391
+ | **Timeline** | Per-session chronological observation view |
392
+ | **Lessons** | Confidence-scored lessons with decay tracking |
393
+ | **Slots** | Pinned memory slots editor |
394
+ | **Replay** | Scrub through past sessions frame by frame |
395
+
396
+ ---
397
+
398
+ ## Deploy to HuggingFace
399
+
400
+ This project is designed to run as a HuggingFace Space. Data is stored in an HF dataset repo and restored on every boot — so no persistent disk is needed.
401
+
402
+ ### Setup
403
+
404
+ 1. Fork this repo as a HuggingFace Space (SDK: Docker)
405
+ 2. Create a dataset repo (e.g. `your-username/agentcache-data`)
406
+ 3. Add Space secrets in the HF dashboard:
407
+
408
+ | Secret | Value |
409
+ |--------|-------|
410
+ | `HF_TOKEN` | Your HF write token |
411
+ | `AGENTCACHE_DATASET_REPO` | `your-username/agentcache-data` |
412
+ | `AGENTCACHE_SECRET` | A random secret (optional but recommended) |
413
+ | `GEMINI_API_KEY` | Gemini key (optional, enables vector search) |
414
+
415
+ 4. The Space boots, restores `agentcache.db` from the dataset repo, and starts the server
416
+
417
+ ### How sync works
418
+
419
+ `sync.py` uses mtime fingerprinting — it only uploads when the database actually changed, so there are no unnecessary uploads during idle periods.
420
+
421
+ ```bash
422
+ # Manual backup
423
+ python sync.py
424
+
425
+ # Environment for sync
426
+ HF_TOKEN=...
427
+ AGENTCACHE_DATASET_REPO=username/agentcache-data
428
+ ```
429
+
430
+ ---
431
+
432
+ ## Architecture
433
+
434
+ ```
435
+ agentcache-python/
436
+ ├── src/
437
+ │ ├── app.py Flask server — all endpoints, WebSocket broadcaster
438
+ │ ├── db.py SQLite StateKV — WAL mode, audit_log table
439
+ │ ├── functions.py Core logic — observe, remember, search, context
440
+ │ ├── search.py BM25 + Gemini vector index + HybridSearch (RRF)
441
+ │ └── viewer/
442
+ │ └── index.html Single-file HTML dashboard (no build step)
443
+ ├── sync.py HuggingFace dataset backup/restore
444
+ ├── Dockerfile HF Space container
445
+ ├── start.sh Boot script (restore → start server → start sync)
446
+ └── requirements.txt 6 Python dependencies, no external DB required
447
+ ```
448
+
449
+ ### Database layout
450
+
451
+ Two SQLite tables in `~/.agentcache/agentcache.db`:
452
+
453
+ ```sql
454
+ -- All data lives here, namespaced by scope
455
+ kv_store (
456
+ scope TEXT NOT NULL, -- e.g. "mem:sessions", "mem:obs:{session_id}"
457
+ key TEXT NOT NULL,
458
+ value TEXT NOT NULL, -- JSON-serialized
459
+ PRIMARY KEY (scope, key)
460
+ )
461
+
462
+ -- Audit trail replaces Dolt git versioning
463
+ audit_log (
464
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
465
+ ts INTEGER NOT NULL, -- unix millis
466
+ agent_id TEXT NOT NULL,
467
+ message TEXT NOT NULL
468
+ )
469
+ ```
470
+
471
+ ### Search pipeline
472
+
473
+ ```
474
+ Query
475
+ → BM25 (always) — Porter-stemmed keyword matching
476
+ → Vector (if Gemini key) — 768-dim cosine similarity
477
+ → RRF fusion — Reciprocal Rank Fusion (k=60)
478
+ → Session diversify — max 3 results per session
479
+ → Return top-K
480
+ ```
481
+
482
+ ---
483
+
484
+ ## vs Original agentcache
485
+
486
+ | | agentcache (Node.js) | agentcache-python |
487
+ |---|---|---|
488
+ | Runtime | Node.js 20+ | Python 3.10+ |
489
+ | Storage | Dolt SQL (git-versioned MySQL) | SQLite WAL (single file) |
490
+ | Engine dependency | iii-engine (separate binary) | None — just Flask |
491
+ | Embeddings | 6 providers + local `@xenova/transformers` | Gemini 768-dim |
492
+ | MCP tools | 53 | 31 |
493
+ | REST endpoints | 128 | ~50 |
494
+ | Deploy | npm, Docker, fly.io, Railway, Render | Docker, HuggingFace Spaces |
495
+ | Cold boot | ~7s (iii engine warm-up) | <2s |
496
+ | Database size | ~232MB (417 Dolt chunk files) | ~20MB (single `.db` file) |
497
+ | Setup | `npm install -g @agentcache/agentcache` | `pip install -r requirements.txt` |
498
+
499
+ Choose the Python version for: simpler setup, HF Space deployment, single-file database, no Node.js, or Python ecosystem integration.
500
+
501
+ Choose the Node.js version for: the full 53-tool MCP surface, iii-engine observability, production multi-agent deployments, or the full auto-hook suite.
502
+
503
+ ---
504
+
505
+ ## Contributing
506
+
507
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
508
+
509
+ Priority areas: test coverage, additional embedding providers, more agent hook scripts.
510
+
511
+ ---
512
+
513
+ ## License
514
+
515
+ Apache-2.0 — see [LICENSE](LICENSE).
agentcache.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,59 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ agentcache.egg-info/PKG-INFO
5
+ agentcache.egg-info/SOURCES.txt
6
+ agentcache.egg-info/dependency_links.txt
7
+ agentcache.egg-info/entry_points.txt
8
+ agentcache.egg-info/requires.txt
9
+ agentcache.egg-info/top_level.txt
10
+ src/__init__.py
11
+ src/app.py
12
+ src/cli.py
13
+ src/connect.py
14
+ src/db.py
15
+ src/functions.py
16
+ src/import_data.py
17
+ src/mcp_stdio.py
18
+ src/replay_import.py
19
+ src/search.py
20
+ src/viewer_helpers.py
21
+ src/workers.py
22
+ src/cache/__init__.py
23
+ src/cache/context.py
24
+ src/cache/graph.py
25
+ src/cache/health.py
26
+ src/cache/observe.py
27
+ src/cache/remember.py
28
+ src/cache/timeline.py
29
+ src/routes/__init__.py
30
+ src/routes/graph.py
31
+ src/routes/health.py
32
+ src/routes/mcp.py
33
+ src/routes/memories.py
34
+ src/routes/migration.py
35
+ src/routes/observations.py
36
+ src/routes/search.py
37
+ src/storage/__init__.py
38
+ src/storage/images.py
39
+ src/storage/paths.py
40
+ src/storage/scopes.py
41
+ src/viewer/favicon.svg
42
+ src/viewer/index.html
43
+ tests/test_api.py
44
+ tests/test_auth.py
45
+ tests/test_context.py
46
+ tests/test_debounce.py
47
+ tests/test_folder_graph_build.py
48
+ tests/test_folder_observe.py
49
+ tests/test_forget.py
50
+ tests/test_graph.py
51
+ tests/test_migration.py
52
+ tests/test_normalize.py
53
+ tests/test_obs_lookup.py
54
+ tests/test_observe_core.py
55
+ tests/test_properties.py
56
+ tests/test_remember.py
57
+ tests/test_route_regressions.py
58
+ tests/test_search.py
59
+ tests/test_timeline.py
agentcache.egg-info/dependency_links.txt ADDED
@@ -0,0 +1 @@
 
 
1
+
agentcache.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ [console_scripts]
2
+ agentcache = src.cli:main
agentcache.egg-info/requires.txt ADDED
@@ -0,0 +1,13 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ flask>=3.0.0
2
+ flask-sock>=0.7.0
3
+ requests>=2.31.0
4
+ python-dateutil>=2.8.2
5
+ huggingface_hub>=0.20.0
6
+ websockets>=12.0
7
+
8
+ [dev]
9
+ pytest>=8.0.0
10
+ hypothesis>=6.100.0
11
+
12
+ [local-embeddings]
13
+ sentence-transformers>=2.7.0
agentcache.egg-info/top_level.txt ADDED
@@ -0,0 +1 @@
 
 
1
+ src