Spaces:
Sleeping
Sleeping
fix: Readme ref links are fixed
Browse files- CONTRIBUTING.md +1 -1
- INSTALL_FOR_AGENTS.md +2 -2
- README.md +2 -14
- agentcache.egg-info/PKG-INFO +515 -0
- agentcache.egg-info/SOURCES.txt +59 -0
- agentcache.egg-info/dependency_links.txt +1 -0
- agentcache.egg-info/entry_points.txt +2 -0
- agentcache.egg-info/requires.txt +13 -0
- agentcache.egg-info/top_level.txt +1 -0
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/
|
| 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/
|
| 21 |
-
cd agentcache
|
| 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/
|
| 72 |
-
cd agentcache
|
| 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> •
|
| 60 |
+
<a href="#features">Features</a> •
|
| 61 |
+
<a href="#mcp-integration">MCP</a> •
|
| 62 |
+
<a href="#api-reference">API</a> •
|
| 63 |
+
<a href="#configuration">Config</a> •
|
| 64 |
+
<a href="#deploy-to-huggingface">Deploy</a> •
|
| 65 |
+
<a href="#viewer">Viewer</a> •
|
| 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
|