AGENTS.md

# agentcache-python — Agent Instructions

## What this project is

A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no iii-engine, no Dolt. Agents use it to store observations scoped to `(folder_path, agent_id)` pairs and global long-term memories. The viewer, MCP tools, and REST API are built around the **folder-based memory model** — sessions, lessons, slots, and actions are removed.

## Project layout

```
src/
├── app.py              Thin Flask factory — create_app(), WebSocket, CORS hook
├── cli.py              CLI entrypoint (agentcache serve/migrate/export)
├── connect.py          Client connection helper
├── db.py               StateKV — SQLite WAL, per-thread connections, stats()
├── functions.py        All canonical business logic (large; memory/ shims delegate here)
├── search.py           BM25 + VectorIndex + HybridSearch + 3 embedding providers
├── viewer_helpers.py   Viewer HTML injection helper
├── workers.py          Background threads — index rebuild, auto-forget, SIGTERM handler
│
├── routes/             Flask blueprints
│   ├── observations.py   /observe, /agent/observe, /folders, /folder/observations
│   ├── memories.py       /remember, /agent/remember, /memories, /forget
│   ├── search.py         /search, /timeline
│   ├── graph.py          /graph, /graph/stats, /graph/query, /graph/build
│   ├── health.py         /livez, /health, /audit, /config/flags
│   ├── mcp.py            /mcp/tools GET+POST (12 active tools)
│   └── migration.py      /migrate
│
├── memory/             Thin shim package — delegates to functions.py
│   ├── observe.py        folder_observe, observe, build_synthetic_compression, strip_private_data
│   ├── remember.py       remember, forget, jaccard_similarity
│   ├── context.py        context, export_data, rebuild_index
│   ├── graph.py          folder_graph_build
│   ├── timeline.py       folder_timeline, folder_search
│   └── health.py         health_check, auto_forget
│
├── storage/            KV scope registry + path/ID utilities
│   ├── scopes.py         KV class (mirrored from functions.py)
│   ├── paths.py          normalize_folder_path, validate_agent_id, generate_id, fingerprint_id
│   └── images.py         save_image_to_disk, delete_image, touch_image
│
└── viewer/
    └── index.html      Single-file HTML dashboard (4 tabs: Folders / Memories / Graph / Timeline)

sync.py             HuggingFace dataset backup/restore
Dockerfile          HF Space container definition
start.sh            Boot: restore DB → start server → start sync loop
requirements.txt    flask, flask-sock, requests, websockets, python-dateutil, huggingface_hub
pyproject.toml      pip-installable package (agentcache==0.9.8, Python ≥3.10)
tests/              pytest suite — unit, integration, and Hypothesis property tests
```

## Running

```bash
pip install -r requirements.txt
python src/app.py
# Server on http://localhost:3111
# Viewer at http://localhost:3111/viewer
```

No build step. No external database. SQLite file lives at `~/.agentcache/agentcache.db`.

## Architecture

### Data Model — Folder-Based Memory

The primary unit of storage is `(folder_path, agent_id)`. Each agent accumulates observations scoped to the folder it is working in. Global long-term memories remain unchanged.

### Storage — `src/db.py`

`StateKV` wraps a single SQLite file with:
- `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — all data as JSON
- `audit_log(id, ts, agent_id, message)` — write audit trail
- `sync_state_metadata(key, value)` — HuggingFace sync watermark

Per-thread persistent connections via `threading.local()`. WAL checkpoint registered via `atexit` and on `SIGTERM`/`SIGINT`.

Key scopes (defined in `functions.py` `KV` class and mirrored in `src/storage/scopes.py`):

| Scope | Content |
|-------|---------|
| `mem:folders` | Index of all `(folder_path, agent_id)` pairs — key = `"{path}:{agent}"` |
| `mem:folder:{path}:{agent}` | Observations for a pair — key = obs_id |
| `mem:foldermeta:{path}:{agent}` | Metadata for a pair (obsCount, lastUpdated, summary) |
| `mem:obs_lookup` | O(1) reverse-lookup: obs_id → `{folderPath, agentId}` |
| `mem:memories` | Global long-term memories |
| `mem:index:bm25:*` | Sharded BM25 index (2MB chunks) |
| `mem:audit` | Audit log entries |
| `mem:relations` | Knowledge graph edges |
| `mem:sessions` | Legacy session store (read-only, migration only) |
| `mem:obs:{session_id}` | Legacy per-session observations (read-only, migration only) |

### Business logic — `src/functions.py`

All canonical implementations live here. `src/memory/*` are thin shims that re-export from this module (for future decoupling).

**Observation pipeline:**
```
raw payload → normalize_folder_path() → validate_agent_id() → strip_private_data()
→ build obs dict → kv.set(folder_obs scope) → upsert folder_meta + folders index
→ kv.set(obs_lookup) → BM25-indexed → vector-indexed (if key set)
→ schedule_save() (debounced 5s) → audit log → WebSocket broadcast
```

**Memory versioning:** `remember()` checks Jaccard similarity against existing memories. If > 0.7 match found, new memory supersedes old (`isLatest=False` on old, `parentId` set on new).

**Search:** `folder_search()` uses `HybridSearch` (BM25 + vector, RRF k=60). Falls back to BM25-only when no embedding provider is configured. Results include both folder observations and global memories.

**`health_check()`** returns: `folderCount`, `agentCount`, `pairCount`, `observationCount`, `memoryCount`, `bm25IndexSize`, `vectorIndexSize`, `dbPath`, plus `db.stats()` fields.

### Search — `src/search.py`

- `SearchIndex`: BM25 with Porter stemmer and synonym expansion. Dirty-flag (`_dirty`) prevents unnecessary saves. Persisted in sharded 2MB KV chunks.
- `VectorIndex`: cosine similarity over embeddings stored as base64-encoded float32 arrays. Also has `_dirty` flag.
- `HybridSearch`: fuses BM25 + vector scores with RRF (k=60).

**Embedding providers** (auto-selected by priority in `create_app()`):

| Priority | Provider | Env var | Dimensions |
|----------|----------|---------|------------|
| 1 | `GeminiEmbeddingProvider` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | 768 |
| 2 | `OpenAIEmbeddingProvider` | `OPENAI_API_KEY` | 1536 |
| 3 | `SentenceTransformerProvider` | `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | variable |
| 4 | BM25-only | — | — |

### Server — `src/app.py`

Boot order:
1. Load `~/.agentcache/.env` if present
2. Initialize `StateKV` (SQLite)
3. Auto-select embedding provider (Gemini → OpenAI → SentenceTransformer → BM25-only)
4. Initialize `IndexPersistence` (load or rebuild)
5. Backfill `obs_lookup` index if missing
6. Create Flask app, register blueprints
7. Set up WebSocket `/stream/mem-live/viewer`
8. Register CORS `after_request` hook
9. Start background workers (index rebuild if empty/stale, auto-forget loop)

Auth: all endpoints check `AGENTCACHE_SECRET` via `hmac.compare_digest`. `/livez` is always open.

## MCP Tools

The server exposes **12 MCP tools** via `GET /agentcache/mcp/tools` and `POST /agentcache/mcp/tools`.

| Tool | Description | Status |
|------|-------------|--------|
| `agent_observe` | Log observation to a `(folderPath, agentId)` pair | Working |
| `agent_remember` | Save to global long-term memory | Working |
| `memory_recall` | Search folder obs + global memories (BM25+vector) | Working |
| `memory_smart_search` | Hybrid semantic+keyword search (alias for recall) | Working |
| `memory_save` | Explicitly save insight to long-term memory | Working |
| `memory_export` | Export all data as JSON (v2 format) | Working |
| `memory_forget` | Delete memory or folder pair observations | Working |
| `memory_diagnose` | Health check (folder/agent/obs/memory counts) | Working |
| `memory_folders` | List all `(folder, agent)` pairs | Working |
| `memory_folder_observations` | Get observations for a specific pair | Working |
| `memory_timeline` | Folder activity feed (sorted by time, filterable) | Working |

**MCP stdio wrapper:** `src/mcp_stdio.py` reads `AGENTCACHE_URL` and `AGENTCACHE_SECRET` from environment variables dynamically.

## Consistency rules

**When adding a REST endpoint:**
1. Add the route in the appropriate `src/routes/*.py` blueprint
2. Update the `API Reference` section in `README.md`
3. Add the MCP tool in `src/routes/mcp.py` if it should be agent-callable

**When adding an MCP tool:**
1. Add the schema to the `GET /mcp/tools` response in `src/routes/mcp.py`
2. Add the handler case to the `POST /mcp/tools` dispatch in `src/routes/mcp.py`
3. Update the tool table in `README.md`
4. Update `AGENTS.md` tool list

**When changing data scopes:**
1. Update the `KV` class in `src/functions.py` (canonical)
2. Mirror the change in `src/storage/scopes.py`
3. Update the scope table in this file

## Code patterns

### Adding a new KV scope

```python
# In src/functions.py KV class (canonical):
class KV:
    your_scope = "mem:your-scope"

    @staticmethod
    def your_dynamic_scope(id: str) -> str:
        return f"mem:your-scope:{id}"
```

### Adding a REST endpoint

```python
# In the appropriate src/routes/*.py blueprint:
@your_bp.route('/agentcache/your-path', methods=['POST'])
def your_endpoint():
    auth_err = _check_auth()
    if auth_err:
        return auth_err
    body = request.get_json(force=True) or {}
    # validate fields explicitly — never pass raw body to functions
    result = functions.your_function(_get_kv(), body.get('field'))
    return jsonify(result), 200
```

### Adding an MCP tool schema

In `src/routes/mcp.py`, `GET /agentcache/mcp/tools` handler:
```python
{
    "name": "memory_your_tool",
    "description": "What it does",
    "inputSchema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "..."}
        },
        "required": ["query"]
    }
}
```

In `src/routes/mcp.py`, `POST /agentcache/mcp/tools` handler:
```python
elif tool_name == 'memory_your_tool':
    query = args.get('query', '')
    result = functions.your_function(kv, query)
    return jsonify({'content': [{'type': 'text', 'text': json.dumps(result)}]})
```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `III_REST_PORT` / `PORT` | `3111` | Server port |
| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables Gemini vector search (priority 1) |
| `OPENAI_API_KEY` | — | Enables OpenAI vector search (priority 2) |
| `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | — | SentenceTransformer model name (priority 3) |
| `AGENTCACHE_SECRET` | — | Bearer token auth |
| `AGENT_ID` | — | Default agent ID |
| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filter data to current agent |
| `AGENTCACHE_CWD` | — | Fallback folder path for legacy clients |
| `MAX_OBS_PER_FOLDER` | `2000` | Observations hard cap per (folder, agent) pair |
| `TOKEN_BUDGET` | `2000` | Context compilation cap |
| `GRAPH_EXTRACTION_ENABLED` | `false` | Graph extraction (needs LLM) |
| `CONSOLIDATION_ENABLED` | `false` | Consolidation (needs LLM) |
| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM compression |
| `AUTO_FORGET_ENABLED` | — | Auto-forget sweep (set to "false" to disable) |
| `AGENTCACHE_CORS_ORIGINS` | see app.py | Comma-separated allowed origins |
| `AGENTCACHE_IMAGE_STORE_MAX_BYTES` | 500MB | Image store byte limit |
| `HF_TOKEN` | — | HuggingFace sync |
| `AGENTCACHE_DATASET_REPO` | — | HF dataset repo for backup |

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

Tests live in `tests/` — 17 test files covering unit tests, integration tests (Flask test client), and Hypothesis property tests.

Key test files:
- `tests/test_properties.py` — 8 correctness properties (pair isolation, obs count consistency, index coverage, privacy, timeline ordering, forget completeness, memory version uniqueness, path normalization idempotency)
- `tests/test_api.py` — Flask test client integration tests
- `tests/test_route_regressions.py` — regression suite after blueprint split

## HuggingFace Space deployment

Data flow: `agentcache.db` (SQLite) ↔ `sync.py` ↔ HF dataset repo.

`start.sh` sequence:
1. Restore `agentcache.db` from dataset repo
2. Start `python src/app.py` in background
3. Run `sync.py` in a loop (backup every ~60s if changed)

## Viewer — `src/viewer/index.html`

Single-file HTML dashboard, served directly by Flask at `/viewer`. No build step, no bundler.

Tabs: **Folders**, **Memories**, **Graph**, **Timeline**.

- **Folders tab**: lists all `(folder, agent)` pairs; click a row to drill into observations
- **Memories tab**: global long-term memories with search
- **Graph tab**: force-directed graph — nodes = folder paths, edges = same-parent / cross-ref / agent-shared
- **Timeline tab**: all observations sorted by timestamp desc, filterable by folder path and agent ID