Raplh 2 in process

.scratch/arch-improvements/issues/01-appcontext-expand.md

@@ -1,16 +0,0 @@
-# 01 — Introduce `AppContext` dataclass (Expand)
-
-**Blocked by:** None — can start immediately
-**Status:** ready-for-agent
-
-## What to build
-
-Introduce a single `AppContext` dataclass that packages all runtime state currently scattered as module-level globals in `functions.py` (`_bm25_index`, `_vector_index`, `_embedding_provider`, `_hybrid_search`, `_stream_broadcaster`, and the `kv` reference). Construct one `AppContext` instance inside `create_app()` and thread it through to every function that needs it. The existing globals stay in place as a compatibility shim — no callers are changed in this ticket. Zero behaviour change; this is the expand step that makes the god-module split (tickets 05–08) possible.
-
-## Acceptance criteria
-
-- [ ] `AppContext` dataclass exists in a new `context.py` module (or equivalent) with typed fields for `kv`, `bm25`, `vector`, `embedder`, and `broadcast`
-- [ ] `create_app()` constructs one `AppContext` and stores it on the Flask app (e.g. `app.ctx`)
-- [ ] The five existing `set_*` functions in `functions.py` remain working — globals are still set alongside the new `AppContext`
-- [ ] All existing tests pass with no changes
-- [ ] No route handler or worker is changed in this ticket

.scratch/arch-improvements/issues/02-privacy-module.md

@@ -1,17 +0,0 @@
-# 02 — Extract `privacy.py` deep module
-
-**Blocked by:** None — can start immediately
-**Status:** ready-for-agent
-
-## What to build
-
-Extract `strip_private_data()` from `functions.py` into a dedicated `privacy.py` module. The new module exposes a single `scrub(text: str, patterns=DEFAULT_PATTERNS) -> str` interface. The regex pattern list is promoted to a public, documented constant (`DEFAULT_PATTERNS`) and is extensible via an env var (`AGENTCACHE_REDACT_PATTERNS`). `functions.py` calls `privacy.scrub()` internally — all existing callers continue working without change. First unit tests for Privacy Scrub are added in this ticket, targeting `scrub()` directly.
-
-## Acceptance criteria
-
-- [ ] `privacy.py` exists with a `scrub(text, patterns=DEFAULT_PATTERNS)` function
-- [ ] `DEFAULT_PATTERNS` is a documented list of regex strings — visible and auditable
-- [ ] An env var `AGENTCACHE_REDACT_PATTERNS` (comma-separated regex strings) appends additional patterns at startup
-- [ ] `functions.py` no longer contains the scrubbing regex list — it imports and calls `privacy.scrub()`
-- [ ] Unit tests cover: API key pattern, bearer token pattern, custom pattern via argument, no false positives on safe text
-- [ ] All existing tests pass

.scratch/arch-improvements/issues/03-auth-middleware.md

@@ -1,16 +0,0 @@
-# 03 — Centralise auth middleware
-
-**Blocked by:** None — can start immediately
-**Status:** ready-for-agent
-
-## What to build
-
-Replace the copy-pasted `_check_auth()` function that currently lives independently in every route blueprint (`mcp.py`, `observations.py`, `memories.py`, `health.py`, and others) with a single `require_auth` decorator defined in a new `auth.py` module. Every route that previously called `_check_auth()` at the top of its handler switches to the `@require_auth` decorator. The auth logic (timing-safe `hmac.compare_digest` Bearer token check) is identical — this is purely a deduplication. RBAC can be added in one place in a future ticket.
-
-## Acceptance criteria
-
-- [ ] `auth.py` exists with a `require_auth(f)` decorator that performs the timing-safe Bearer token check
-- [ ] Every route blueprint imports and uses `@require_auth` — no blueprint defines its own `_check_auth`
-- [ ] A request with no secret configured passes through (existing behaviour preserved)
-- [ ] A request with a wrong token still gets a `401` response
-- [ ] All existing tests pass

.scratch/arch-improvements/issues/04-mcp-tool-registry.md

@@ -1,17 +0,0 @@
-# 04 — MCP tool registry (replace elif chain)
-
-**Blocked by:** 03 — centralise auth middleware
-**Status:** ready-for-agent
-
-## What to build
-
-Replace the 300-line `if/elif` dispatch chain in `routes/mcp.py` with a `@register("tool_name")` decorator registry. Each of the 30+ MCP tool handlers becomes a standalone function decorated with `@register`. The dispatcher becomes a two-liner: look up the tool name in the registry dict and call the handler. Auth is handled by the shared `@require_auth` decorator from ticket 03. The tool schema list (`get_mcp_tools_schemas`) stays as-is. No change to the MCP wire format or agent behaviour.
-
-## Acceptance criteria
-
-- [ ] A `_tools: dict[str, Callable]` registry exists and a `@register(name)` decorator populates it
-- [ ] Every MCP tool handler is a standalone function — not an inline block inside a giant if/elif
-- [ ] The POST `/mcp/tools` handler body is ≤ 20 lines (lookup + call + error handling)
-- [ ] Each tool handler function is independently importable and callable in a test without starting Flask
-- [ ] Adding a new tool requires only adding a new decorated function — no editing of existing dispatch code
-- [ ] All existing MCP tool calls produce the same responses as before

.scratch/arch-improvements/issues/05-split-observations-memories.md

@@ -1,23 +0,0 @@
-# 05 — Split god module batch 1: `observations.py` + `memories.py`
-
-**Blocked by:** 01 — AppContext dataclass (Expand)
-**Status:** ready-for-agent
-
-## What to build
-
-Move the first two major domain areas out of `functions.py` into focused modules, using the domain vocabulary from `UBIQUITOUS_LANGUAGE.md`.
-
-**`observations.py`** receives: `folder_observe()`, `observe()` (legacy), `dedup_folder_observations()`, `build_synthetic_compression()`, `infer_type()`, `extract_files()`, `extract_image()`, image store helpers (`save_image_to_disk`, `delete_image`, `touch_image`, `is_managed_image_path`), and `normalize_folder_path()` / `validate_agent_id()`.
-
-**`memories.py`** receives: `remember()`, `forget()`, memory versioning logic, and `jaccard_similarity()`.
-
-`functions.py` re-exports everything from these two modules so all existing callers continue to work unchanged. CI must stay green. This is the first batch of the expand phase of the god-module split.
-
-## Acceptance criteria
-
-- [ ] `observations.py` and `memories.py` exist as standalone modules
-- [ ] All moved functions accept `AppContext` (from ticket 01) instead of reaching into module-level globals, while also accepting the legacy `kv: StateKV` signature for backward compat
-- [ ] `functions.py` re-exports every moved symbol — no call site outside `functions.py` needs to change
-- [ ] Existing route blueprints and workers continue to import from `functions` without modification
-- [ ] All existing tests pass
-- [ ] No logic is changed — this is a pure relocation

.scratch/arch-improvements/issues/06-split-indexing-retrieval.md

@@ -1,24 +0,0 @@
-# 06 — Split god module batch 2: `indexing.py` + `retrieval.py`
-
-**Blocked by:** 05 — split batch 1 (observations + memories)
-**Status:** ready-for-agent
-
-## What to build
-
-Move the second major domain area out of `functions.py`.
-
-**`indexing.py`** receives: `IndexPersistence`, `rebuild_index()`, `backfill_obs_lookup_if_needed()`, `vector_index_add_guarded()`, `clip_embed_input()`, and all index-related helpers. This module owns the Index Rebuild lifecycle (see `UBIQUITOUS_LANGUAGE.md`).
-
-**`retrieval.py`** receives: `folder_search()`, `folder_timeline()`, `compile_context()`, and `export_data()`. This module owns the Recall, Smart Search, Folder Search, Timeline, and Context Compilation operations.
-
-`functions.py` continues to re-export everything. CI stays green.
-
-## Acceptance criteria
-
-- [ ] `indexing.py` and `retrieval.py` exist as standalone modules
-- [ ] All moved functions use `AppContext` from ticket 01 rather than reaching into globals directly
-- [ ] `functions.py` re-exports every moved symbol unchanged
-- [ ] `IndexPersistence` is importable from `indexing` in `workers.py` without changing any other worker code
-- [ ] `folder_search()` and `compile_context()` are callable from a test by constructing an `AppContext` with an in-memory KV and a fresh `SearchIndex` — no Flask app required
-- [ ] All existing tests pass
-- [ ] No logic is changed

.scratch/arch-improvements/issues/07-split-consolidation-slots-lessons.md

@@ -1,25 +0,0 @@
-# 07 — Split god module batch 3: `consolidation.py` + `slots.py` + `lessons.py`
-
-**Blocked by:** 06 — split batch 2 (indexing + retrieval)
-**Status:** ready-for-agent
-
-## What to build
-
-Move the final major domain areas out of `functions.py`.
-
-**`consolidation.py`** receives: `consolidate()`, `auto_forget()`, `folder_graph_build()`, and all LLM-call helpers used exclusively by the Consolidation pipeline. This module owns the Consolidation lifecycle (Working Memory → Episodic → Semantic → Procedural).
-
-**`slots.py`** receives: all Slot CRUD functions (`get_slots`, `set_slot`, `delete_slot`, `reflect_slot`, `append_slot`, etc.).
-
-**`lessons.py`** receives: all Lesson CRUD functions (`get_lessons`, `save_lesson`, `search_lessons`, `strengthen_lesson`, lesson decay logic).
-
-`functions.py` re-exports everything. After this ticket, `functions.py` is a pure shim — no domain logic remains in it.
-
-## Acceptance criteria
-
-- [ ] `consolidation.py`, `slots.py`, and `lessons.py` exist as standalone modules
-- [ ] `functions.py` contains no domain logic — only re-export statements
-- [ ] All moved functions use `AppContext` from ticket 01
-- [ ] `auto_forget()` is callable from a test without importing `functions` directly
-- [ ] All existing tests pass
-- [ ] No logic is changed

.scratch/arch-improvements/issues/08-delete-functions-shim.md

@@ -1,23 +0,0 @@
-# 08 — Contract: delete `functions.py` shim, migrate all callers to direct imports
-
-**Blocked by:** 05, 06, 07 — all three split batches must be complete
-**Status:** ready-for-agent
-
-## What to build
-
-Delete `functions.py` entirely. Update every import across `routes/`, `workers.py`, `app.py`, and the test suite to point directly to the focused module that owns the symbol. This is the contract step of the expand–contract sequence. After this ticket the domain vocabulary from `UBIQUITOUS_LANGUAGE.md` is directly reflected in the module names — there is no god module.
-
-Import mapping (non-exhaustive):
-- `from .functions import folder_observe` → `from .observations import folder_observe`
-- `from .functions import remember, forget` → `from .memories import remember, forget`
-- `from .functions import folder_search, compile_context` → `from .retrieval import folder_search, compile_context`
-- `from .functions import IndexPersistence, rebuild_index` → `from .indexing import IndexPersistence, rebuild_index`
-- `from .functions import consolidate, auto_forget` → `from .consolidation import consolidate, auto_forget`
-
-## Acceptance criteria
-
-- [ ] `functions.py` does not exist in the repository
-- [ ] `rg "from .functions import\|from agentcache.functions import\|import functions"` returns zero results in `src/`
-- [ ] All existing tests pass with imports updated
-- [ ] No test imports from `functions` — each test imports from the specific module it exercises
-- [ ] CI is green

.scratch/arch-improvements/issues/09-typed-observations-table-expand.md

@@ -1,19 +0,0 @@
-# 09 — Add typed `observations` table to SQLite (Expand)
-
-**Blocked by:** 05 — observations module must exist to own this migration
-**Status:** ready-for-agent
-
-## What to build
-
-Add a typed `observations` table to the SQLite schema with columns for `folder`, `agent`, `timestamp`, `type`, `importance`, and `text`. When a new Observation is ingested via `folder_observe()`, write it to both the new typed table and the existing `kv_store` scope (dual-write). Reads still use `kv_store` — zero behaviour change for any query path. This is the expand step that makes SQL-level filtering possible without breaking anything.
-
-The new table enables: `WHERE folder = ? AND agent = ? AND timestamp > ?` and `ORDER BY importance DESC LIMIT N` entirely at the SQLite layer — no Python-side filtering needed.
-
-## Acceptance criteria
-
-- [ ] `observations(id TEXT PK, folder TEXT, agent TEXT, timestamp TEXT, type TEXT, importance INTEGER, text TEXT)` table exists in the DB schema with indexes on `(folder, agent, timestamp)` and `(importance)`
-- [ ] `folder_observe()` dual-writes: one row to `observations`, one entry to `kv_store` (existing path)
-- [ ] The DB migration runs automatically on startup if the table does not exist (no manual step)
-- [ ] All reads continue to use `kv_store` — no query is changed in this ticket
-- [ ] All existing tests pass
-- [ ] A DB integrity test verifies that for each `kv_store` Observation entry written, a matching row exists in `observations`

.scratch/arch-improvements/issues/10-typed-observations-reads-contract.md

@@ -1,18 +0,0 @@
-# 10 — Migrate Observation reads to typed table (Contract)
-
-**Blocked by:** 09 — typed observations table (Expand) must be complete
-**Status:** ready-for-agent
-
-## What to build
-
-Switch `folder_search`, `folder_timeline`, `compile_context`, and `auto_forget` to read Observations from the typed `observations` table using SQL-level filtering, replacing the current pattern of `kv.list(scope)` + Python-side filtering. Stop dual-writing new Observations to `kv_store` — the typed table is now the single source of truth. A one-time migration backfills any existing `kv_store` Observation entries into the typed table for users upgrading from a previous version.
-
-## Acceptance criteria
-
-- [ ] `folder_timeline()` issues a single `SELECT … WHERE folder=? AND agent=? ORDER BY timestamp DESC LIMIT ?` — no Python-side filtering loop
-- [ ] `folder_search()` hydrates candidates from the typed table rather than `kv.list(scope)` for the Observation load step
-- [ ] `compile_context()` fetches recent Observations using `ORDER BY importance DESC, timestamp DESC LIMIT ?` at the SQL layer
-- [ ] New `folder_observe()` calls write only to the typed table (no `kv_store` Observation scope write)
-- [ ] A backfill function runs once on startup to migrate existing `kv_store` Observations into the typed table
-- [ ] A benchmark test (or manual note in the PR) shows query latency improvement at ≥ 10k Observations
-- [ ] All existing tests pass

.scratch/arch-improvements/issues/11-basevectorindex-protocol.md

@@ -1,17 +0,0 @@
-# 11 — `BaseVectorIndex` protocol + `InMemoryVectorIndex` adapter
-
-**Blocked by:** 06 — indexing module must exist before its interface is formalised
-**Status:** ready-for-agent
-
-## What to build
-
-Define a `BaseVectorIndex` Protocol (or ABC) in `indexing.py` with three methods: `add(obs_id, session_id, embedding)`, `remove(obs_id)`, and `search(query_embedding, limit) -> list`. Rename the current flat-list implementation to `InMemoryVectorIndex` and have it implement `BaseVectorIndex`. Update `AppContext.vector` to be typed as `BaseVectorIndex`. Behaviour is completely unchanged — this ticket only cuts the adapter seam so future backends (HNSW, Qdrant, Chroma) can be swapped in without touching `retrieval.py` or `consolidation.py`.
-
-## Acceptance criteria
-
-- [ ] `BaseVectorIndex` Protocol exists in `indexing.py` with `add`, `remove`, and `search` as the only required methods
-- [ ] `InMemoryVectorIndex` implements `BaseVectorIndex` and passes a `isinstance(idx, BaseVectorIndex)` check
-- [ ] `AppContext.vector` is typed as `BaseVectorIndex | None`
-- [ ] A test constructs a minimal stub that implements `BaseVectorIndex` and passes it to `folder_search()` via `AppContext` — confirming the seam is real and injectable
-- [ ] `VectorIndex` (old name) remains as an alias for `InMemoryVectorIndex` for one release to avoid breaking any external imports
-- [ ] All existing tests pass with no behaviour change

src/agentcache.egg-info/PKG-INFO

@@ -1,4 +1,4 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: agentcache
 Version: 0.9.8
 Summary: A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite
@@ -35,486 +35,4 @@ Requires-Dist: ruff>=0.3.0; extra == "dev"
 Requires-Dist: twine>=5.0.0; extra == "dev"
 Provides-Extra: local-embeddings
 Requires-Dist: sentence-transformers>=2.7.0; extra == "local-embeddings"
-
----
-title: AgentCache Python
-emoji: 🧠
-colorFrom: blue
-colorTo: indigo
-sdk: docker
-pinned: false
----
-
-<h1 align="center">agentcache-python</h1>
-
-<p align="center">
-  <strong>Persistent memory for AI coding agents — pure Python, zero external databases.</strong><br/>
-  Works with Claude Code, Cursor, Cline, Windsurf, Gemini CLI, and any MCP client.
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10+" />
-  <img src="https://img.shields.io/badge/SQLite-WAL-003B57?style=for-the-badge&logo=sqlite&logoColor=white" alt="SQLite WAL" />
-  <img src="https://img.shields.io/badge/Flask-3.0-000000?style=for-the-badge&logo=flask&logoColor=white" alt="Flask 3.0" />
-  <img src="https://img.shields.io/badge/MCP-Compatible-6B21A8?style=for-the-badge" alt="MCP Compatible" />
-  <img src="https://img.shields.io/badge/HuggingFace-Space-FF9D00?style=for-the-badge&logo=huggingface&logoColor=white" alt="HuggingFace Space" />
-</p>
-
-<p align="center">
-  <a href="#quick-start">Quick Start</a> &bull;
-  <a href="#features">Features</a> &bull;
-  <a href="#mcp-integration">MCP</a> &bull;
-  <a href="#api-reference">API</a> &bull;
-  <a href="#configuration">Config</a> &bull;
-  <a href="#deploy-to-huggingface">Deploy</a> &bull;
-  <a href="#viewer">Viewer</a> &bull;
-  <a href="#architecture">Architecture</a>
-</p>
-
----
-
-## What Is This?
-
-**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.
-
-Key differences from the Node.js original:
-
-- **No Node.js or iii-engine** — runs with plain `python src/app.py`
-- **SQLite instead of Dolt** — single file, WAL mode, instant startup
-- **HuggingFace Space ready** — deploys in one click, data synced to an HF dataset repo
-- **Same REST + MCP wire format** — drop-in for any agent already wired to agentcache
-
-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.
-
----
-
-## Quick Start
-
-### Run locally
-
-```bash
-# Clone
-git clone https://github.com/Yashwant00CR7/agentcache.git
-cd agentcache
-
-# Install dependencies (no build step)
-pip install -r requirements.txt
-
-# Start the server
-python src/app.py
-```
-
-Server starts on **http://localhost:3111**. Open the viewer at http://localhost:3111/viewer.
-
-### Verify it works
-
-```bash
-# Health check
-curl http://localhost:3111/agentcache/livez
-# {"status": "ok"}
-
-# Save a memory
-curl -X POST http://localhost:3111/agentcache/remember \
-  -H "Content-Type: application/json" \
-  -d '{"content": "JWT auth uses jose middleware in src/middleware/auth.ts", "concepts": ["auth", "jwt"]}'
-
-# Recall it
-curl -X POST http://localhost:3111/agentcache/search \
-  -H "Content-Type: application/json" \
-  -d '{"query": "authentication middleware", "limit": 5}'
-```
-
----
-
-## Features
-
-| Feature | Status | Notes |
-|---------|--------|-------|
-| REST API — sessions, memories, observations | ✅ | Full surface |
-| WebSocket live stream | ✅ | `/stream/mem-live/viewer` |
-| MCP tools endpoint | ✅ | 31 tools |
-| Built-in HTML viewer | ✅ | Real-time dashboard at `/viewer` |
-| BM25 keyword search | ✅ | Always on, no API key needed |
-| Hybrid BM25 + vector search | ✅ | Requires `GEMINI_API_KEY` |
-| 4-tier memory consolidation | ⚙️ | `CONSOLIDATION_ENABLED=true` + LLM key |
-| Knowledge graph extraction | ⚙️ | `GRAPH_EXTRACTION_ENABLED=true` + LLM key |
-| LLM observation compression | ⚙️ | `AGENTCACHE_AUTO_COMPRESS=true` + LLM key |
-| Lessons with confidence decay | ✅ | Fingerprinted, auto-strengthen on repeat |
-| Memory slots (pinned context) | ✅ | CRUD + auto-reflect |
-| Session replay | ✅ | Full timeline in viewer |
-| Audit log | ✅ | Tracks every write with agent_id + timestamp |
-| HuggingFace Space deploy | ✅ | One-click, data synced to dataset repo |
-| Privacy filtering | ✅ | Strips API keys, tokens before storage |
-
-### 4-Tier Memory Model
-
-Inspired by how human memory works — raw experience → compressed episodes → extracted facts → learned patterns.
-
-| Tier | What | When |
-|------|------|------|
-| **Working** | Raw observations from tool use | Every tool call |
-| **Episodic** | Compressed session summaries | Session end |
-| **Semantic** | Extracted facts and patterns | Consolidation |
-| **Procedural** | Workflows and decision patterns | Consolidation |
-
----
-
-## MCP Integration
-
-Wire agentcache-python into your agent's MCP config. It speaks the same MCP protocol as the Node.js original.
-
-### Most agents (Cursor, Claude Desktop, Cline, Windsurf)
-
-```json
-{
-  "mcpServers": {
-    "agentcache": {
-      "command": "npx",
-      "args": ["-y", "@agentcache/mcp"],
-      "env": {
-        "AGENTCACHE_URL": "http://localhost:3111"
-      }
-    }
-  }
-}
-```
-
-### Claude Code
-
-Paste this prompt and your agent will wire everything:
-
-```
-Start agentcache-python: run `python src/app.py` from the agentcache-python directory.
-Then add this MCP server to ~/.claude.json under mcpServers:
-{
-  "agentcache": {
-    "command": "npx",
-    "args": ["-y", "@agentcache/mcp"],
-    "env": { "AGENTCACHE_URL": "http://localhost:3111" }
-  }
-}
-Verify with: curl http://localhost:3111/agentcache/livez
-Open the viewer at: http://localhost:3111/viewer
-```
-
-### Available MCP Tools (31)
-
-| Tool | Description |
-|------|-------------|
-| `memory_save` | Save a long-term insight, decision, or pattern |
-| `memory_recall` | Search past observations by keyword |
-| `memory_smart_search` | Hybrid BM25 + vector semantic search |
-| `memory_sessions` | List recent sessions |
-| `memory_sessions_list` | Retrieve all memory sessions |
-| `memory_timeline` | Chronological observations for a session |
-| `memory_observations` | Observations for a session |
-| `memory_profile` | Per-project concept + file profile |
-| `memory_lessons` | List active lessons with confidence scores |
-| `memory_lesson_save` | Save a lesson (duplicate saves strengthen it) |
-| `memory_lesson_recall` | Search lessons by query |
-| `memory_lesson_search` | Search lessons by keywords |
-| `memory_consolidate` | Run 4-tier memory consolidation |
-| `memory_reflect` | Reflect on session, update context |
-| `memory_diagnose` | Health check across all subsystems |
-| `memory_forget` | Delete memory, session, or observations |
-| `memory_export` | Export all memory data as JSON |
-| `agent_observe` | Log agent execution observation |
-| `agent_remember` | Save agent cache to long-term storage |
-| `memory_antigravity_sync` | Sync Antigravity transcripts to memory |
-| `memory_antigravity_sync_all` | Master sync: transcript + crystallize + reflect |
-| `memory_slot_list` | List all pinned memory slots |
-| `memory_slot_get` | Retrieve a specific pinned memory slot |
-| `memory_slot_create` | Create/overwrite a pinned memory slot |
-| `memory_slot_append` | Append text content to a pinned memory slot |
-| `memory_slot_replace` | Replace pinned memory slot content |
-| `memory_slot_delete` | Delete a pinned memory slot |
-| `memory_action_create` | Create a new work item / action |
-| `memory_action_update` | Update fields of an existing action |
-| `memory_frontier` | Get active and pending actions sorted by priority |
-| `memory_crystallize` | Crystallize/summarize observations in a session |
-
----
-
-## API Reference
-
-Base URL: `http://localhost:3111/agentcache`
-
-### Health
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/livez` | Liveness probe — no auth required |
-
-### Sessions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/session/start` | Start a new session |
-| `POST` | `/session/end` | End a session |
-| `POST` | `/session/commit` | Commit session with summary |
-| `GET` | `/sessions` | List all sessions |
-
-### Observations
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/observe` | Ingest a hook event observation |
-| `POST` | `/agent/observe` | Simplified observe for direct agent use |
-| `GET` | `/observations` | List observations (`?session_id=`) |
-| `POST` | `/timeline` | Chronological observation window |
-
-### Memories
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `POST` | `/remember` | Save long-term memory |
-| `POST` | `/agent/remember` | Simplified remember |
-| `POST` | `/forget` | Delete memory / session / observations |
-| `POST` | `/search` | BM25 + vector search |
-| `POST` | `/context` | Compile context for a session + project |
-| `GET` | `/memories` | List memories (`?latest=true&limit=N`) |
-| `POST` | `/evolve` | Create a new memory version |
-
-### Lessons
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/lessons` | List lessons |
-| `POST` | `/lessons` | Create lesson |
-| `POST` | `/lessons/search` | Search lessons |
-| `POST` | `/lessons/strengthen` | Reinforce an existing lesson |
-
-### Slots
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/slots` | List all pinned slots |
-| `POST` | `/slot` | Create or update a slot |
-| `GET` | `/slot` | Get slot by name |
-| `DELETE` | `/slot` | Delete a slot |
-| `POST` | `/slot/reflect` | Auto-populate from session observations |
-
-### Graph + Profile
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/relations` | Knowledge graph edges |
-| `POST` | `/relations` | Add a relation |
-| `GET` | `/profile` | Project profile (top concepts, files) |
-
-### Actions
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/actions` | List actions |
-| `POST` | `/actions` | Create an action |
-| `PATCH` | `/actions/<id>` | Update action status / fields |
-| `GET` | `/frontier` | Pending actions sorted by priority |
-| `GET` | `/insights` | List insights |
-
-### Replay
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/replay/sessions` | Sessions list for replay tab |
-| `GET` | `/replay/load` | Full session + observations (`?sessionId=`) |
-
-### MCP
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/mcp/tools` | MCP tool schema list |
-| `POST` | `/mcp/tools` | MCP tool call dispatch |
-
----
-
-## Configuration
-
-Create `~/.agentcache/.env` (no `export` prefix needed):
-
-```env
-# Server port
-III_REST_PORT=3111
-
-# Vector search — enables Gemini 768-dim embeddings
-GEMINI_API_KEY=your-gemini-key
-
-# LLM for compression / consolidation / graph extraction
-# Any one of these enables LLM features:
-ANTHROPIC_API_KEY=your-anthropic-key
-# OPENAI_API_KEY=your-openai-key
-# GEMINI_API_KEY=your-key   (same key as above works for both)
-
-# LLM-powered features (disabled by default — spend tokens)
-CONSOLIDATION_ENABLED=true
-GRAPH_EXTRACTION_ENABLED=true
-AGENTCACHE_AUTO_COMPRESS=true
-
-# Context injection limits
-TOKEN_BUDGET=2000
-MAX_OBS_PER_SESSION=500
-
-# Auth — set to require Bearer token on all endpoints
-AGENTCACHE_SECRET=your-secret
-
-# Agent scope isolation
-AGENT_ID=my-agent
-AGENTCACHE_AGENT_SCOPE=isolated   # only see this agent's data
-
-# HuggingFace sync
-HF_TOKEN=your-hf-token
-AGENTCACHE_DATASET_REPO=username/agentcache-data
-```
-
-### Full Variable Reference
-
-| Variable | Default | Purpose |
-|----------|---------|---------|
-| `III_REST_PORT` / `PORT` | `3111` | API server port |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search |
-| `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
-| `AGENT_ID` | — | Default agent ID for scope isolation |
-| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filters data to current `AGENT_ID` |
-| `MAX_OBS_PER_SESSION` | `500` | Hard cap on observations per session |
-| `TOKEN_BUDGET` | `2000` | Max tokens in compiled context |
-| `GRAPH_EXTRACTION_ENABLED` | `false` | Knowledge graph (needs LLM) |
-| `CONSOLIDATION_ENABLED` | `false` | Memory consolidation (needs LLM) |
-| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM observation compression |
-
----
-
-## Viewer
-
-Built-in dashboard at **http://localhost:3111/viewer**.
-
-| Tab | What You See |
-|-----|-------------|
-| **Dashboard** | Session stats, memory counts, recent activity |
-| **Sessions** | Browse sessions, inspect observations |
-| **Memories** | Search, filter, and read long-term memories |
-| **Graph** | Project folder visualization — nodes = folders, edges = shared concepts or parent path |
-| **Timeline** | Per-session chronological observation view |
-| **Lessons** | Confidence-scored lessons with decay tracking |
-| **Slots** | Pinned memory slots editor |
-| **Replay** | Scrub through past sessions frame by frame |
-
----
-
-## Deploy to HuggingFace
-
-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.
-
-### Setup
-
-1. Fork this repo as a HuggingFace Space (SDK: Docker)
-2. Create a dataset repo (e.g. `your-username/agentcache-data`)
-3. Add Space secrets in the HF dashboard:
-
-   | Secret | Value |
-   |--------|-------|
-   | `HF_TOKEN` | Your HF write token |
-   | `AGENTCACHE_DATASET_REPO` | `your-username/agentcache-data` |
-   | `AGENTCACHE_SECRET` | A random secret (optional but recommended) |
-   | `GEMINI_API_KEY` | Gemini key (optional, enables vector search) |
-
-4. The Space boots, restores `agentcache.db` from the dataset repo, and starts the server
-
-### How sync works
-
-`sync.py` uses mtime fingerprinting — it only uploads when the database actually changed, so there are no unnecessary uploads during idle periods.
-
-```bash
-# Manual backup
-python sync.py
-
-# Environment for sync
-HF_TOKEN=...
-AGENTCACHE_DATASET_REPO=username/agentcache-data
-```
-
----
-
-## Architecture
-
-```
-agentcache-python/
-├── src/
-│   ├── app.py          Flask server — all endpoints, WebSocket broadcaster
-│   ├── db.py           SQLite StateKV — WAL mode, audit_log table
-│   ├── functions.py    Core logic — observe, remember, search, context
-│   ├── search.py       BM25 + Gemini vector index + HybridSearch (RRF)
-│   └── viewer/
-│       └── index.html  Single-file HTML dashboard (no build step)
-├── sync.py             HuggingFace dataset backup/restore
-├── Dockerfile          HF Space container
-├── start.sh            Boot script (restore → start server → start sync)
-└── requirements.txt    6 Python dependencies, no external DB required
-```
-
-### Database layout
-
-Two SQLite tables in `~/.agentcache/agentcache.db`:
-
-```sql
--- All data lives here, namespaced by scope
-kv_store (
-  scope TEXT NOT NULL,    -- e.g. "mem:sessions", "mem:obs:{session_id}"
-  key   TEXT NOT NULL,
-  value TEXT NOT NULL,    -- JSON-serialized
-  PRIMARY KEY (scope, key)
-)
-
--- Audit trail replaces Dolt git versioning
-audit_log (
-  id       INTEGER PRIMARY KEY AUTOINCREMENT,
-  ts       INTEGER NOT NULL,   -- unix millis
-  agent_id TEXT NOT NULL,
-  message  TEXT NOT NULL
-)
-```
-
-### Search pipeline
-
-```
-Query
-  → BM25 (always)         — Porter-stemmed keyword matching
-  → Vector (if Gemini key) — 768-dim cosine similarity
-  → RRF fusion            — Reciprocal Rank Fusion (k=60)
-  → Session diversify     — max 3 results per session
-  → Return top-K
-```
-
----
-
-## vs Original agentcache
-
-| | agentcache (Node.js) | agentcache-python |
-|---|---|---|
-| Runtime | Node.js 20+ | Python 3.10+ |
-| Storage | Dolt SQL (git-versioned MySQL) | SQLite WAL (single file) |
-| Engine dependency | iii-engine (separate binary) | None — just Flask |
-| Embeddings | 6 providers + local `@xenova/transformers` | Gemini 768-dim |
-| MCP tools | 53 | 31 |
-| REST endpoints | 128 | ~50 |
-| Deploy | npm, Docker, fly.io, Railway, Render | Docker, HuggingFace Spaces |
-| Cold boot | ~7s (iii engine warm-up) | <2s |
-| Database size | ~232MB (417 Dolt chunk files) | ~20MB (single `.db` file) |
-| Setup | `npm install -g @agentcache/agentcache` | `pip install -r requirements.txt` |
-
-Choose the Python version for: simpler setup, HF Space deployment, single-file database, no Node.js, or Python ecosystem integration.
-
-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.
-
----
-
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome.
-
-Priority areas: test coverage, additional embedding providers, more agent hook scripts.
-
----
-
-## License
-
-Apache-2.0 — see [LICENSE](LICENSE).
+Dynamic: license-file

src/agentcache.egg-info/SOURCES.txt

@@ -1,5 +1,4 @@
 LICENSE
-README.md
 pyproject.toml
 src/agentcache/__init__.py
 src/agentcache/app.py
@@ -26,6 +25,9 @@ src/agentcache/cache/health.py
 src/agentcache/cache/observe.py
 src/agentcache/cache/remember.py
 src/agentcache/cache/timeline.py
+src/agentcache/core/__init__.py
+src/agentcache/core/kv_scopes.py
+src/agentcache/core/search_service.py
 src/agentcache/routes/__init__.py
 src/agentcache/routes/graph.py
 src/agentcache/routes/health.py
@@ -42,6 +44,8 @@ src/agentcache/viewer/favicon.svg
 src/agentcache/viewer/index.html
 tests/test_api.py
 tests/test_auth.py
+tests/test_auto_forget.py
+tests/test_cli_context.py
 tests/test_context.py
 tests/test_debounce.py
 tests/test_folder_graph_build.py
@@ -56,4 +60,5 @@ tests/test_properties.py
 tests/test_remember.py
 tests/test_route_regressions.py
 tests/test_search.py
+tests/test_security.py
 tests/test_timeline.py

src/agentcache/__init__.py

@@ -6,13 +6,10 @@ __version__ = "0.9.8"
 
 from .app import create_app
 from .connect import run_connect
+from .core import KV, ObservationEvents, ObservationStore, SearchService
 from .db import StateKV
-from .functions import (
+from .legacy import (
     folder_graph_build,
-    folder_observe,
-    folder_search,
-    folder_timeline,
-    forget,
     health_check,
     remember,
 )
@@ -22,11 +19,11 @@ __all__ = [
     "create_app",
     "StateKV",
     "run_connect",
-    "folder_observe",
-    "folder_search",
-    "folder_timeline",
+    "KV",
+    "ObservationStore",
+    "ObservationEvents",
+    "SearchService",
     "folder_graph_build",
     "remember",
-    "forget",
     "health_check",
 ]

src/agentcache/app.py

@@ -13,7 +13,7 @@ import sys
 from flask import Flask, request, send_from_directory
 from flask_sock import Sock
 
-from . import functions
+from . import legacy
 
 # Prevent double-import of app when run directly as __main__
 if __name__ == "__main__":
@@ -41,26 +41,30 @@ def _load_env() -> None:
 
 _load_env()
 
-# Module-level globals — set once by create_app(), read by blueprints via `import app`
+# Module-level singletons — set once by init_services(), read by blueprints and workers.
 kv = None
 embedding_provider = None
-persistence = None
+persistence = None  # kept for backward compat with workers; use search_service instead
+search_service = None  # SearchService instance
+observation_store = None  # ObservationStore instance
 
 
 def init_services() -> tuple:
-    """Initialise database, embedding provider, and index persistence."""
-    global kv, embedding_provider, persistence
+    """Initialise database, SearchService, ObservationStore, and legacy persistence shim."""
+    global kv, embedding_provider, persistence, search_service, observation_store
     if kv is not None:
         return kv, embedding_provider, persistence
 
-    from . import functions
     from . import search as search_mod
+    from .core.observation_store import ObservationEvents, ObservationStore
+    from .core.search_service import SearchService
     from .db import StateKV
+    from .search import SearchIndex, VectorIndex
 
     # 1. DB
     kv = StateKV()
 
-    # 2. Embedding provider — auto-select by priority (D5.3):
+    # 2. Embedding provider — auto-select by priority:
     #    GEMINI_API_KEY → OPENAI_API_KEY → AGENTCACHE_LOCAL_EMBEDDING_MODEL → BM25-only
     api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
     openai_key = os.getenv("OPENAI_API_KEY")
@@ -71,7 +75,6 @@ def init_services() -> tuple:
     if api_key:
         try:
             embedding_provider = search_mod.GeminiEmbeddingProvider(api_key)
-            functions.set_embedding_provider(embedding_provider)
             print(
                 f"[search] Embedding provider active: gemini ({embedding_provider.dimensions} dims)"
             )
@@ -80,7 +83,6 @@ def init_services() -> tuple:
     elif openai_key:
         try:
             embedding_provider = search_mod.OpenAIEmbeddingProvider(openai_key)
-            functions.set_embedding_provider(embedding_provider)
             print(
                 f"[search] Embedding provider active: openai ({embedding_provider.dimensions} dims)"
             )
@@ -89,7 +91,6 @@ def init_services() -> tuple:
     elif local_model:
         try:
             embedding_provider = search_mod.SentenceTransformerProvider(local_model)
-            functions.set_embedding_provider(embedding_provider)
             print(
                 f"[search] Embedding provider active: sentence-transformers/{local_model} ({embedding_provider.dimensions} dims)"
             )
@@ -100,22 +101,27 @@ def init_services() -> tuple:
     else:
         print("[search] No embedding API key found — running in BM25-only mode.")
 
-    # 3. Index persistence — use embedding_provider variable set above
-    has_vector = embedding_provider is not None
-    persistence = functions.IndexPersistence(
-        kv,
-        functions._bm25_index,
-        functions._vector_index if has_vector else None,
+    # 3. Construct SearchService and ObservationStore with injected dependencies.
+    bm25 = SearchIndex()
+    vector = VectorIndex() if embedding_provider is not None else None
+    search_service = SearchService(bm25, vector, embedding_provider, kv)
+    observation_store = ObservationStore(
+        kv, search_service=search_service, events=ObservationEvents()
     )
-    functions.set_index_persistence(persistence)
-    loaded = persistence.load()
+
+    # Load persisted indexes.
+    loaded = search_service.load_persisted()
     print(
         f"[persistence] Load results: BM25={loaded['bm25']}, Vector={loaded['vector']}"
     )
 
-    # Backfill coordinate lookup index if missing/incomplete
+    # Keep persistence reference for workers backward compat.
+    persistence = search_service._persistence
+
+    # Backfill coordinate lookup index if missing/incomplete.
     try:
-        functions.backfill_obs_lookup_if_needed(kv)
+        if observation_store is not None:
+            observation_store.backfill_lookup()
     except Exception as e:
         print(f"[db] Warning backfilling obs_lookup: {e}")
 
@@ -136,6 +142,9 @@ def create_app() -> Flask:
 
     # 4. Flask app + blueprints
     flask_app = Flask(__name__)
+    flask_app.extensions["observation_store"] = observation_store
+    flask_app.extensions["search_service"] = search_service
+
     from werkzeug.middleware.proxy_fix import ProxyFix
 
     flask_app.wsgi_app = ProxyFix(
@@ -143,7 +152,9 @@ def create_app() -> Flask:
     )
     from .routes import register_blueprints
 
-    register_blueprints(flask_app)
+    register_blueprints(
+        flask_app, observation_store=observation_store, search_service=search_service
+    )
 
     # 5. WebSocket broadcaster
     sock = Sock(flask_app)
@@ -176,7 +187,10 @@ def create_app() -> Flask:
             except Exception:
                 _ws_clients.discard(ws)
 
-    functions.set_stream_broadcaster(_broadcast)
+    legacy.set_stream_broadcaster(_broadcast)
+
+    if observation_store and observation_store.events:
+        observation_store.events.on_added.append(_broadcast)
 
     # 6. Viewer static routes
     from importlib.resources import files

src/agentcache/cache/__init__.py

@@ -18,7 +18,8 @@ callers may import from this package (A2.2).
 # Each name is imported lazily via a try/except so missing items don't break
 # the package import on partially-initialised environments.
 # ---------------------------------------------------------------------------
-from .. import functions as _fn  # noqa: E402
+from .. import legacy as _fn  # noqa: E402
+from ..core import KV
 from .context import context, export_data, rebuild_index
 from .graph import folder_graph_build
 from .health import auto_forget, health_check
@@ -31,14 +32,10 @@ from .observe import (
 from .remember import forget, jaccard_similarity, remember
 from .timeline import folder_search, folder_timeline
 
-KV = _fn.KV
 generate_id = _fn.generate_id
 fingerprint_id = _fn.fingerprint_id
 normalize_folder_path = _fn.normalize_folder_path
 validate_agent_id = _fn.validate_agent_id
-IndexPersistence = _fn.IndexPersistence
-set_embedding_provider = _fn.set_embedding_provider
-set_index_persistence = _fn.set_index_persistence
 set_stream_broadcaster = _fn.set_stream_broadcaster
 get_agent_id = _fn.get_agent_id
 record_audit = _fn.record_audit
@@ -72,15 +69,12 @@ __all__ = [
     # health.py
     "health_check",
     "auto_forget",
-    # functions.py shims (A2.2)
+    # legacy.py shims
     "KV",
     "generate_id",
     "fingerprint_id",
     "normalize_folder_path",
     "validate_agent_id",
-    "IndexPersistence",
-    "set_embedding_provider",
-    "set_index_persistence",
     "set_stream_broadcaster",
     "get_agent_id",
     "record_audit",

src/agentcache/cache/context.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from .. import functions as _fn
+from .. import legacy as _fn
 from ..db import StateKV
 
 

src/agentcache/cache/graph.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from .. import functions as _fn
+from .. import legacy as _fn
 from ..db import StateKV
 
 

src/agentcache/cache/health.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from .. import functions as _fn
+from .. import legacy as _fn
 from ..db import StateKV
 
 

src/agentcache/cache/observe.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from .. import functions as _fn  # access module-level globals (_bm25_index, etc.)
+from .. import legacy as _fn  # access module-level globals (_bm25_index, etc.)
 from ..db import StateKV
 
 # Re-export for backward compatibility

src/agentcache/cache/remember.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from .. import functions as _fn
+from .. import legacy as _fn
 from ..db import StateKV
 
 

src/agentcache/cache/timeline.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
-from .. import functions as _fn
+from .. import legacy as _fn
 from ..db import StateKV
 
 

src/agentcache/cli.py

@@ -28,7 +28,7 @@ def cmd_serve(args) -> None:
 def cmd_migrate(args) -> None:
     """Run session → folder migration."""
     from .db import StateKV
-    from .functions import migrate_sessions_to_folders
+    from .legacy import migrate_sessions_to_folders
 
     kv = StateKV()
     result = migrate_sessions_to_folders(kv, dry_run=args.dry_run)
@@ -54,7 +54,7 @@ def cmd_migrate(args) -> None:
 def cmd_export(args) -> None:
     """Export all data as JSON."""
     from .db import StateKV
-    from .functions import export_data
+    from .legacy import export_data
 
     kv = StateKV()
     data = export_data(kv, {})
@@ -113,7 +113,8 @@ def cmd_context(args) -> None:
     import time
 
     from .app import init_services
-    from .functions import KV, normalize_folder_path
+    from .core import KV
+    from .core.observation_store import normalize_folder_path
 
     # 1. Resolve folder and agent
     cwd = os.getcwd()

src/agentcache/core/__init__.py

@@ -10,5 +10,10 @@ from .kv_scopes import KV
 from .observation_store import ObservationEvents, ObservationStore
 from .search_service import IndexPersistence, SearchService
 
-__all__ = ["KV", "SearchService", "IndexPersistence", "ObservationStore", "ObservationEvents"]
-
+__all__ = [
+    "KV",
+    "SearchService",
+    "IndexPersistence",
+    "ObservationStore",
+    "ObservationEvents",
+]

src/agentcache/core/kv_scopes.py

@@ -5,8 +5,6 @@ Single source of truth for every SQLite scope string used in the system.
 Import this module wherever a KV scope key is needed — routes, stores, workers.
 """
 
-from typing import Optional
-
 
 class KV:
     # ---- Folder memory scopes ----

src/agentcache/core/observation_store.py

@@ -104,8 +104,7 @@ class ObservationStore:
         folder_path = normalize_folder_path(folder_path_raw)
         agent_id = validate_agent_id(agent_id_raw)
 
-        from ..legacy import strip_private_data, infer_type, extract_files
-
+        from ..legacy import extract_files, infer_type, strip_private_data
 
         safe_text = strip_private_data(text_raw)[:4000]
 
@@ -116,7 +115,11 @@ class ObservationStore:
         dedup_lock = self._get_dedup_lock(folder_path, agent_id)
         with dedup_lock:
             existing_dedup = self.kv.get(KV.obs_dedup(folder_path, agent_id), dedup_fp)
-            if existing_dedup and isinstance(existing_dedup, dict) and existing_dedup.get("obsId"):
+            if (
+                existing_dedup
+                and isinstance(existing_dedup, dict)
+                and existing_dedup.get("obsId")
+            ):
                 return {"observationId": existing_dedup["obsId"], "deduplicated": True}
 
             max_obs = int(os.getenv("MAX_OBS_PER_FOLDER", "2000"))
@@ -267,7 +270,6 @@ class ObservationStore:
         total_kept = 0
 
         for pair in pairs:
-
             fp = pair["folderPath"]
             aid = pair["agentId"]
             all_obs = self.kv.list(KV.folder_obs(fp, aid))
@@ -292,7 +294,9 @@ class ObservationStore:
                         duplicates.append(obs["id"])
 
             if duplicates:
-                self.forget({"folderPath": fp, "agentId": aid, "observationIds": duplicates})
+                self.forget(
+                    {"folderPath": fp, "agentId": aid, "observationIds": duplicates}
+                )
                 total_removed += len(duplicates)
 
             total_kept += len(fingerprint_map)
@@ -305,7 +309,6 @@ class ObservationStore:
                     {"obsId": obs["id"], "timestamp": obs.get("timestamp", "")},
                 )
 
-
         return {
             "success": True,
             "deduplicated": total_removed,
@@ -323,7 +326,6 @@ class ObservationStore:
         deleted = 0
         deleted_mem_ids: List[str] = []
         deleted_obs_ids: List[str] = []
-        deleted_session = False
 
         if memory_id:
             mem = self.kv.get(KV.memories, memory_id)
@@ -351,8 +353,6 @@ class ObservationStore:
             if "observationIds" in data and data["observationIds"] is not None:
                 partial_deleted = 0
                 for oid in obs_ids:
-
-
                     obs = self.kv.get(obs_scope, oid)
                     existed = self.kv.delete(obs_scope, oid)
                     if existed:
@@ -385,7 +385,9 @@ class ObservationStore:
                         try:
                             cb(deleted_obs_ids)
                         except Exception as ex:
-                            print(f"[observation_store] Error in on_deleted callback: {ex}")
+                            print(
+                                f"[observation_store] Error in on_deleted callback: {ex}"
+                            )
             else:
                 all_obs = self.kv.list(obs_scope)
                 for obs in all_obs:
@@ -411,7 +413,9 @@ class ObservationStore:
                         try:
                             cb(fp, aid)
                         except Exception as ex:
-                            print(f"[observation_store] Error in on_folder_deleted callback: {ex}")
+                            print(
+                                f"[observation_store] Error in on_folder_deleted callback: {ex}"
+                            )
 
         if session_id and obs_ids:
             for oid in obs_ids:
@@ -454,7 +458,6 @@ class ObservationStore:
                 deleted += 1
             self.kv.delete(KV.sessions, session_id)
             self.kv.delete(KV.summaries, session_id)
-            deleted_session = True
             deleted += 2
 
         if deleted > 0 and self.search_service:
@@ -474,7 +477,9 @@ class ObservationStore:
         index_entries = self.kv.list(KV.folders)
 
         if folder_path is not None:
-            index_entries = [e for e in index_entries if e.get("folderPath") == folder_path]
+            index_entries = [
+                e for e in index_entries if e.get("folderPath") == folder_path
+            ]
 
         if agent_id is not None:
             index_entries = [e for e in index_entries if e.get("agentId") == agent_id]
@@ -568,5 +573,3 @@ class ObservationStore:
             self.search_service.schedule_persist()
 
         return total_indexed
-
-

src/agentcache/core/search_service.py

@@ -8,7 +8,6 @@ MemoryStore, routes) call this service instead of touching index globals.
 from __future__ import annotations
 
 import json
-import math
 import sqlite3
 import threading
 import time
@@ -24,7 +23,9 @@ class IndexPersistence:
 
     DEBOUNCE_SECONDS: float = 5.0
 
-    def __init__(self, kv: Any, bm25: SearchIndex, vector: Optional[VectorIndex] = None):
+    def __init__(
+        self, kv: Any, bm25: SearchIndex, vector: Optional[VectorIndex] = None
+    ):
         self.kv = kv
         self.bm25 = bm25
         self.vector = vector
@@ -149,14 +150,20 @@ class IndexPersistence:
                             cursor.close()
                     except sqlite3.OperationalError as ex:
                         err_msg = str(ex).lower()
-                        if ("locked" in err_msg or "busy" in err_msg) and attempt < max_retries - 1:
+                        if (
+                            "locked" in err_msg or "busy" in err_msg
+                        ) and attempt < max_retries - 1:
                             time.sleep(delay)
                             delay *= 2
                             continue
-                        print(f"[index persistence] error cleaning up obsolete shards: {ex}")
+                        print(
+                            f"[index persistence] error cleaning up obsolete shards: {ex}"
+                        )
                         break
                     except Exception as ex:
-                        print(f"[index persistence] error cleaning up obsolete shards: {ex}")
+                        print(
+                            f"[index persistence] error cleaning up obsolete shards: {ex}"
+                        )
                         break
 
         if (
@@ -372,7 +379,11 @@ class SearchService:
                             results.append(result)
                             seen_ids.add(obs_id)
                             # Lazy backfill lookup
-                            active_kv.set(KV.obs_lookup, obs_id, {"folderPath": fp, "agentId": aid})
+                            active_kv.set(
+                                KV.obs_lookup,
+                                obs_id,
+                                {"folderPath": fp, "agentId": aid},
+                            )
                             found = True
                             break
                     if found:

src/agentcache/legacy.py

@@ -2,11 +2,9 @@
 
 import datetime
 import hashlib
-
 import json
 import os
 import re
-import sqlite3
 import threading
 import time
 import uuid
@@ -15,7 +13,6 @@ from typing import Any, Dict, List, Optional, Set, Tuple
 from .core.kv_scopes import KV  # noqa: F401  re-exported for backward compat
 from .core.search_service import IndexPersistence  # noqa: F401
 from .db import StateKV
-from .search import HybridSearch, SearchIndex, VectorIndex
 
 # =====================================================================
 # Global Variables / Module State
@@ -811,7 +808,8 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
         if k in raw_for_synthetic:
             synthetic[k] = raw_for_synthetic[k]
     kv.set(KV.observations(session_id), obs_id, synthetic)
-    if _search_service: _search_service.bm25.add(synthetic)
+    if _search_service:
+        _search_service.bm25.add(synthetic)
 
     comb_text = synthetic["title"] + " " + (synthetic.get("narrative") or "")
     vector_index_add_guarded(
@@ -854,9 +852,11 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
 
 def _get_observation_store(kv: StateKV):
     from . import app as app_module
+
     if getattr(app_module, "observation_store", None) is not None:
         return app_module.observation_store
     from .core.observation_store import ObservationStore
+
     return ObservationStore(kv, search_service=_search_service)
 
 
@@ -876,7 +876,6 @@ def dedup_folder_observations(
     return store.dedup(folder_path_raw, agent_id_raw)
 
 
-
 # =====================================================================
 # Folder-Based Search (folder_search)
 # =====================================================================
@@ -918,7 +917,6 @@ def folder_timeline(
     )
 
 
-
 # =====================================================================
 # Memory System (Remember, Forget, Evolve)
 # =====================================================================
@@ -1052,7 +1050,6 @@ def forget(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     return store.forget(data)
 
 
-
 # =====================================================================
 # Prompt Context Compilation System
 # =====================================================================
@@ -1958,7 +1955,6 @@ def rebuild_index(kv: StateKV) -> int:
     return store.rebuild_index()
 
 
-
 # =====================================================================
 # Advanced Function Stubs / CRUD Operations
 # =====================================================================
@@ -2540,7 +2536,8 @@ def auto_forget(kv: StateKV, dry_run: bool = False) -> Dict[str, Any]:
                 refs = kv.get(KV.imageRefs, ref) or 0
                 if refs > 0:
                     kv.set(KV.imageRefs, ref, refs - 1)
-            if _search_service: _search_service.remove(mem_id)
+            if _search_service:
+                _search_service.remove(mem_id)
 
         # Commit evictions for session-based observations
         for sid, obs_id in evicted_observations:
@@ -2578,7 +2575,8 @@ def auto_forget(kv: StateKV, dry_run: bool = False) -> Dict[str, Any]:
                 ).hexdigest()
                 kv.delete(KV.obs_dedup(fp, aid), dedup_fp)
 
-            if _search_service: _search_service.remove(obs_id)
+            if _search_service:
+                _search_service.remove(obs_id)
 
             pair_key = (fp, aid)
             folder_deletes[pair_key] = folder_deletes.get(pair_key, 0) + 1
@@ -2729,7 +2727,6 @@ def health_check(kv: StateKV) -> Dict[str, Any]:
     }
 
 
-
 def strip_xml_wrappers(raw: str) -> str:
     if not raw:
         return ""
@@ -3543,7 +3540,9 @@ def backfill_obs_lookup_if_needed(kv: StateKV) -> None:
     store.backfill_lookup()
 
 
-def verify_index_sync_on_boot(kv: StateKV, search_service: Optional[Any] = None) -> bool:
+def verify_index_sync_on_boot(
+    kv: StateKV, search_service: Optional[Any] = None
+) -> bool:
     """Check if the search index size matches the database counts.
     Returns True if in sync, False if a rebuild is needed.
     """
@@ -3551,6 +3550,7 @@ def verify_index_sync_on_boot(kv: StateKV, search_service: Optional[Any] = None)
         svc = search_service or _search_service
         if svc is None:
             from . import app as app_module
+
             svc = getattr(app_module, "search_service", None)
 
         # 1. Total folder obs count
@@ -3577,4 +3577,3 @@ def verify_index_sync_on_boot(kv: StateKV, search_service: Optional[Any] = None)
     except Exception as e:
         print(f"[persistence] verify_index_sync_on_boot failed: {e}")
         return False
-

src/agentcache/replay_import.py

@@ -219,7 +219,7 @@ def derive_crystal_and_lessons(
     compressed: List[Dict[str, Any]],
     first_prompt: str = None,
 ) -> None:
-    from .functions import KV
+    from .core import KV
 
     if not raw_obs:
         return
@@ -368,7 +368,8 @@ def find_jsonl_files(root: str, limit=200) -> Tuple[List[str], bool, int, bool]:
 
 
 def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str, Any]:
-    from .functions import KV, _bm25_index, build_synthetic_compression
+    from .core import KV
+    from .legacy import build_synthetic_compression
 
     default_root = os.path.expanduser(os.path.join("~", ".claude", "projects"))
     raw_path = path or default_root
@@ -481,24 +482,12 @@ def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str,
             }
             kv.set(KV.sessions, session["id"], session)
 
-        from .functions import vector_index_add_guarded
-
         compressed = []
         for obs in parsed["observations"]:
             synthetic = build_synthetic_compression(obs)
             compressed.append(synthetic)
             kv.set(KV.observations(parsed["sessionId"]), obs["id"], synthetic)
 
-            # Index
-            _bm25_index.add(synthetic)
-            comb_text = synthetic["title"] + " " + (synthetic.get("narrative") or "")
-            vector_index_add_guarded(
-                synthetic["id"],
-                synthetic["sessionId"],
-                comb_text,
-                {"kind": "synthetic", "logId": synthetic["id"]},
-            )
-
         observation_count += len(parsed["observations"])
         session_ids.append(parsed["sessionId"])
 
@@ -511,18 +500,9 @@ def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str,
             first_prompt,
         )
 
-    # Save the updated persistence state
-    from . import functions
-
-    if functions._index_persistence:
-        try:
-            functions._index_persistence.save()
-        except Exception as e:
-            print(f"[import-jsonl] Warning saving index persistence: {e}")
-
     # Audit trail
     try:
-        from .functions import log_audit
+        from .legacy import log_audit
 
         log_audit(
             kv,

src/agentcache/routes/__init__.py

@@ -4,31 +4,26 @@ Flask blueprints for agentmemory-python.
 Import and register all blueprints via register_blueprints(app).
 """
 
-from .graph import create_graph_bp
-from .health import create_health_bp
+from .graph import graph_bp
+from .health import health_bp
 from .mcp import mcp_bp
-from .memories import create_memories_bp
+from .memories import memories_bp
 from .migration import migration_bp
 from .observations import create_observations_bp, observations_bp
 from .search import search_bp
 
 
-def register_blueprints(app, observation_store=None, search_service=None, kv=None):
+def register_blueprints(app, observation_store=None, search_service=None):
     """Register all route blueprints on a Flask application instance."""
     obs_bp = (
         create_observations_bp(observation_store)
         if observation_store
         else observations_bp
     )
-    if kv is None and observation_store is not None:
-        kv = observation_store.kv
     app.register_blueprint(obs_bp)
-    app.register_blueprint(create_memories_bp(kv))
+    app.register_blueprint(memories_bp)
     app.register_blueprint(search_bp)
-    app.register_blueprint(create_graph_bp(kv))
-    app.register_blueprint(create_health_bp(kv))
+    app.register_blueprint(graph_bp)
+    app.register_blueprint(health_bp)
     app.register_blueprint(mcp_bp)
     app.register_blueprint(migration_bp)
-
-
-

src/agentcache/routes/graph.py

@@ -22,6 +22,7 @@ def create_graph_bp(kv=None):
         if kv is not None:
             return kv
         from .. import app as app_module
+
         return app_module.kv
 
     # ------------------------------------------------------------------
@@ -81,5 +82,4 @@ def create_graph_bp(kv=None):
     return bp
 
 
-
 graph_bp = create_graph_bp(None)

src/agentcache/routes/health.py

@@ -25,6 +25,7 @@ def create_health_bp(kv=None, embedding_provider=None):
         if kv is not None:
             return kv
         from .. import app as app_module
+
         return app_module.kv
 
     # ------------------------------------------------------------------
@@ -90,7 +91,6 @@ def create_health_bp(kv=None, embedding_provider=None):
         res = query_audit(_get_kv(), {"operation": op, "limit": limit})
         return jsonify({"entries": res, "success": True}), 200
 
-
     # ------------------------------------------------------------------
     # GET /agentcache/config/flags
     # ------------------------------------------------------------------

src/agentcache/routes/mcp.py

@@ -15,7 +15,6 @@ from flask import Blueprint, jsonify, request
 from .. import legacy
 from ..core import KV
 
-
 mcp_bp = Blueprint("mcp", __name__)
 
 
@@ -52,7 +51,6 @@ def _get_observation_store():
     return app_module.observation_store
 
 
-
 def _datetime_now_iso() -> str:
     return (
         datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
@@ -401,7 +399,11 @@ def mcp_tools_call():
             search_svc = _get_search_service()
             if search_svc is not None:
                 res = search_svc.search(
-                    query=q, limit=limit, folder_path=folder_path, agent_id=agent_id, kv=kv
+                    query=q,
+                    limit=limit,
+                    folder_path=folder_path,
+                    agent_id=agent_id,
+                    kv=kv,
                 )
             else:
                 res = []
@@ -440,7 +442,11 @@ def mcp_tools_call():
             search_svc = _get_search_service()
             if search_svc is not None:
                 res = search_svc.search(
-                    query=q, limit=limit, folder_path=folder_path, agent_id=agent_id, kv=kv
+                    query=q,
+                    limit=limit,
+                    folder_path=folder_path,
+                    agent_id=agent_id,
+                    kv=kv,
                 )
             else:
                 res = []
@@ -475,7 +481,6 @@ def mcp_tools_call():
                 res = {"success": False, "deleted": 0}
             text_out = json.dumps(res, indent=2)
 
-
         elif name in ("cache_export", "memory_export"):
             res = legacy.export_data(kv, {})
             text_out = json.dumps(res, indent=2)

src/agentcache/routes/memories.py

@@ -23,6 +23,7 @@ def create_memories_bp(kv=None):
         if kv is not None:
             return kv
         from .. import app as app_module
+
         return app_module.kv
 
     # ------------------------------------------------------------------
@@ -40,9 +41,6 @@ def create_memories_bp(kv=None):
         except Exception as e:
             return jsonify({"error": str(e)}), 400
 
-
-
-
     # ------------------------------------------------------------------
     # POST /agentmemory/agent/remember
     # ------------------------------------------------------------------
@@ -113,7 +111,6 @@ def create_memories_bp(kv=None):
             res = functions.forget(_get_kv(), body)
             return jsonify(res), 200
         except Exception as e:
-
             return jsonify({"error": str(e)}), 400
 
     return bp

src/agentcache/routes/migration.py

@@ -9,7 +9,7 @@ import os
 
 from flask import Blueprint, jsonify, request
 
-from .. import functions
+from .. import legacy as functions
 
 migration_bp = Blueprint("migration", __name__)
 

src/agentcache/routes/observations.py

@@ -2,21 +2,21 @@
 Observation routes blueprint.
 
 Handles:
-  POST /agentmemory/observe
-  POST /agentmemory/agent/observe
-  GET  /agentmemory/folder/observations
-  GET  /agentmemory/folders
+  POST /agentcache/observe
+  POST /agentcache/agent/observe
+  GET  /agentcache/folder/observations
+  GET  /agentcache/folders
+  POST /agentcache/folder/dedup
 """
 
 import datetime
 import os
+from typing import Optional
 
 from flask import Blueprint, jsonify, request
 
-from .. import functions
-from ..functions import KV
-
-observations_bp = Blueprint("observations", __name__)
+from ..core.kv_scopes import KV
+from ..core.observation_store import ObservationStore
 
 
 def _datetime_now_iso() -> str:
@@ -41,271 +41,255 @@ def _check_auth():
     return None
 
 
-def _get_kv():
-    """Retrieve the shared kv instance from the app module."""
-    from .. import app as app_module
-
-    return app_module.kv
-
-
-# ---------------------------------------------------------------------------
-# POST /agentmemory/observe  (legacy raw hook endpoint + auto-compat shim)
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/observe", methods=["POST"])
-@observations_bp.route("/agentmemory/observe", methods=["POST"])
-def api_observe():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-
-    body = {}
-    try:
-        body = request.get_json(force=True) or {}
-        folder_path = body.get("folderPath")
-        agent_id = body.get("agentId")
-        text = body.get("text") or body.get("content") or ""
-
-        if not folder_path or not agent_id or not text:
-            return jsonify({"error": "folderPath, agentId, and text are required"}), 400
-
-        payload = {
-            "folderPath": folder_path,
-            "agentId": agent_id,
-            "text": text,
-            "timestamp": body.get("timestamp") or _datetime_now_iso(),
-            "type": body.get("type"),
-            "title": body.get("title"),
-            "concepts": body.get("concepts"),
-            "files": body.get("files"),
-            "importance": body.get("importance"),
-        }
-        res = functions.folder_observe(_get_kv(), payload)
-        return jsonify(res), 201
-    except Exception as e:
-        import traceback
-
-        tb = traceback.format_exc()
-        print(f"[observe] 400 — keys={list(body.keys())} {type(e).__name__}: {e}\n{tb}")
-        return jsonify(
-            {
-                "error": str(e),
-                "detail": type(e).__name__,
-                "keys": list(body.keys()),
-                "tb": tb,
+def create_observations_bp(
+    observation_store: Optional[ObservationStore] = None,
+) -> Blueprint:
+    bp = Blueprint("observations", __name__)
+
+    def get_store() -> ObservationStore:
+        if observation_store is not None:
+            return observation_store
+        from flask import current_app
+
+        store = current_app.extensions.get("observation_store")
+        if store is None:
+            from .. import app as app_module
+
+            store = getattr(app_module, "observation_store", None)
+        if store is None:
+            raise RuntimeError("ObservationStore is not initialized")
+        return store
+
+    def get_kv():
+        return get_store().kv
+
+    @bp.route("/agentcache/observe", methods=["POST"])
+    @bp.route("/agentmemory/observe", methods=["POST"])
+    def api_observe():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+
+        body = {}
+        try:
+            body = request.get_json(force=True) or {}
+            folder_path = body.get("folderPath")
+            agent_id = body.get("agentId")
+            text = body.get("text") or body.get("content") or ""
+
+            if not folder_path or not agent_id or not text:
+                return (
+                    jsonify({"error": "folderPath, agentId, and text are required"}),
+                    400,
+                )
+
+            payload = {
+                "folderPath": folder_path,
+                "agentId": agent_id,
+                "text": text,
+                "timestamp": body.get("timestamp") or _datetime_now_iso(),
+                "type": body.get("type"),
+                "title": body.get("title"),
+                "concepts": body.get("concepts"),
+                "files": body.get("files"),
+                "importance": body.get("importance"),
+            }
+            res = get_store().ingest(payload)
+            return jsonify(res), 201
+        except Exception as e:
+            import traceback
+
+            tb = traceback.format_exc()
+            print(
+                f"[observe] 400 — keys={list(body.keys())} {type(e).__name__}: {e}\n{tb}"
+            )
+            return (
+                jsonify(
+                    {
+                        "error": str(e),
+                        "detail": type(e).__name__,
+                        "keys": list(body.keys()),
+                        "tb": tb,
+                    }
+                ),
+                400,
+            )
+
+    @bp.route("/agentcache/agent/observe", methods=["POST"])
+    @bp.route("/agentmemory/agent/observe", methods=["POST"])
+    def api_agent_observe():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+
+        try:
+            body = request.get_json(force=True) or {}
+            folder_path = body.get("folderPath")
+            agent_id = body.get("agentId")
+            text = body.get("text") or body.get("content") or ""
+
+            if not folder_path or not agent_id or not text:
+                return (
+                    jsonify({"error": "folderPath, agentId, and text are required"}),
+                    400,
+                )
+
+            timestamp = body.get("timestamp") or _datetime_now_iso()
+
+            payload = {
+                "folderPath": folder_path,
+                "agentId": agent_id,
+                "text": text,
+                "timestamp": timestamp,
+                "type": body.get("type"),
+                "title": body.get("title"),
+                "concepts": body.get("concepts"),
+                "files": body.get("files"),
+                "importance": body.get("importance"),
             }
-        ), 400
-
 
-# ---------------------------------------------------------------------------
-# POST /agentmemory/agent/observe
-# ---------------------------------------------------------------------------
+            res = get_store().ingest(payload)
+            return jsonify(res), 201
+        except ValueError as e:
+            print(
+                f"[agent_observe] 400 ValueError — body keys: {list(body.keys())} — {e}"
+            )
+            return jsonify({"error": str(e)}), 400
+        except Exception as e:
+            import traceback
+
+            print(
+                f"[agent_observe] 400 error — body keys: {list(body.keys())} — {type(e).__name__}: {e}"
+            )
+            print(traceback.format_exc())
+            return jsonify({"error": str(e), "detail": type(e).__name__}), 400
+
+    @bp.route("/agentcache/folders", methods=["GET"])
+    @bp.route("/agentmemory/folders", methods=["GET"])
+    def api_folders():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+        from .. import legacy
+
+        folders = sorted(
+            get_kv().list(KV.folders),
+            key=lambda x: x.get("lastUpdated", ""),
+            reverse=True,
+        )
+        if legacy.is_agent_scope_isolated():
+            aid = legacy.get_agent_id()
+            if aid:
+                folders = [f for f in folders if f.get("agentId") == aid]
+        return jsonify({"folders": folders}), 200
+
+    @bp.route("/agentcache/folder/observations", methods=["GET"])
+    @bp.route("/agentmemory/folder/observations", methods=["GET"])
+    def api_folder_observations():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+        fp = request.args.get("folderPath")
+        aid = request.args.get("agentId")
+        if not fp or not aid:
+            return jsonify({"error": "folderPath and agentId are required"}), 400
+        from .. import legacy
+
+        if legacy.is_agent_scope_isolated():
+            current_aid = legacy.get_agent_id()
+
+            if current_aid and aid != current_aid:
+                return (
+                    jsonify(
+                        {
+                            "error": "Unauthorized: Agent scope is isolated to another agent"
+                        }
+                    ),
+                    403,
+                )
+        observations = sorted(
+            get_kv().list(KV.folder_obs(fp, aid)),
+            key=lambda x: x.get("timestamp", ""),
+            reverse=True,
+        )
+        return (
+            jsonify({"observations": observations, "folderPath": fp, "agentId": aid}),
+            200,
+        )
 
+    @bp.route("/agentcache/session/start", methods=["POST"])
+    @bp.route("/agentmemory/session/start", methods=["POST"])
+    def api_session_start():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
 
-@observations_bp.route("/agentcache/agent/observe", methods=["POST"])
-@observations_bp.route("/agentmemory/agent/observe", methods=["POST"])
-def api_agent_observe():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
+        import uuid
 
-    try:
         body = request.get_json(force=True) or {}
-        folder_path = body.get("folderPath")
-        agent_id = body.get("agentId")
-        text = body.get("text") or body.get("content") or ""
-
-        if not folder_path or not agent_id or not text:
-            return jsonify({"error": "folderPath, agentId, and text are required"}), 400
-
-        # sessionId accepted but ignored (folder-based model)
-        timestamp = body.get("timestamp") or _datetime_now_iso()
-
-        payload = {
-            "folderPath": folder_path,
-            "agentId": agent_id,
-            "text": text,
-            "timestamp": timestamp,
-            "type": body.get("type"),
-            "title": body.get("title"),
-            "concepts": body.get("concepts"),
-            "files": body.get("files"),
-            "importance": body.get("importance"),
-        }
-
-        res = functions.folder_observe(_get_kv(), payload)
-        return jsonify(res), 201
-    except ValueError as e:
-        import traceback
-
-        print(f"[agent_observe] 400 ValueError — body keys: {list(body.keys())} — {e}")
-        return jsonify({"error": str(e)}), 400
-    except Exception as e:
-        import traceback
-
-        print(
-            f"[agent_observe] 400 error — body keys: {list(body.keys())} — {type(e).__name__}: {e}"
+        session_id = body.get("sessionId") or f"compat_{uuid.uuid4().hex[:16]}"
+        return (
+            jsonify(
+                {
+                    "sessionId": session_id,
+                    "status": "active",
+                    "message": "Session model migrated to folder-based. Use /agentmemory/agent/observe.",
+                }
+            ),
+            200,
         )
-        print(traceback.format_exc())
-        return jsonify({"error": str(e), "detail": type(e).__name__}), 400
-
-
-# ---------------------------------------------------------------------------
-# GET /agentmemory/folders
-# ---------------------------------------------------------------------------
-
 
-@observations_bp.route("/agentcache/folders", methods=["GET"])
-@observations_bp.route("/agentmemory/folders", methods=["GET"])
-def api_folders():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-    folders = sorted(
-        _get_kv().list(KV.folders),
-        key=lambda x: x.get("lastUpdated", ""),
-        reverse=True,
-    )
-    if functions.is_agent_scope_isolated():
-        aid = functions.get_agent_id()
-        if aid:
-            folders = [f for f in folders if f.get("agentId") == aid]
-    return jsonify({"folders": folders}), 200
-
-
-# ---------------------------------------------------------------------------
-# GET /agentmemory/folder/observations
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/folder/observations", methods=["GET"])
-@observations_bp.route("/agentmemory/folder/observations", methods=["GET"])
-def api_folder_observations():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-    fp = request.args.get("folderPath")
-    aid = request.args.get("agentId")
-    if not fp or not aid:
-        return jsonify({"error": "folderPath and agentId are required"}), 400
-    if functions.is_agent_scope_isolated():
-        current_aid = functions.get_agent_id()
-        if current_aid and aid != current_aid:
-            return jsonify(
-                {"error": "Unauthorized: Agent scope is isolated to another agent"}
-            ), 403
-    observations = sorted(
-        _get_kv().list(KV.folder_obs(fp, aid)),
-        key=lambda x: x.get("timestamp", ""),
-        reverse=True,
-    )
-    return jsonify(
-        {"observations": observations, "folderPath": fp, "agentId": aid}
-    ), 200
-
-
-# ---------------------------------------------------------------------------
-# POST /agentmemory/session/start  (legacy compat shim → 200 no-op)
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/session/start", methods=["POST"])
-@observations_bp.route("/agentmemory/session/start", methods=["POST"])
-def api_session_start():
-    """Legacy session/start — clients in the wild still call this.
-    Return a synthetic session ID so callers don't error out.
-    """
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-
-    import uuid
-
-    body = request.get_json(force=True) or {}
-    session_id = body.get("sessionId") or f"compat_{uuid.uuid4().hex[:16]}"
-    return jsonify(
-        {
-            "sessionId": session_id,
-            "status": "active",
-            "message": "Session model migrated to folder-based. Use /agentmemory/agent/observe.",
-        }
-    ), 200
-
-
-# ---------------------------------------------------------------------------
-# POST /agentmemory/session/end  (legacy compat shim → 200 no-op)
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/session/end", methods=["POST"])
-@observations_bp.route("/agentmemory/session/end", methods=["POST"])
-def api_session_end():
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-    return jsonify(
-        {"success": True, "message": "Session model is now folder-based."}
-    ), 200
-
-
-# ---------------------------------------------------------------------------
-# GET /agentmemory/observations  (legacy compat shim)
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/folder/dedup", methods=["POST"])
-@observations_bp.route("/agentmemory/folder/dedup", methods=["POST"])
-def api_folder_dedup():
-    """POST /agentmemory/folder/dedup — remove duplicate observations.
-
-    Body (both optional):
-        folderPath: str  — deduplicate only this folder pair
-        agentId:    str  — deduplicate only this agent
-
-    If both are omitted all folder pairs are processed.
-    Returns: {"success": bool, "deduplicated": int, "pairs_processed": int, "kept": int}
-    """
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-    try:
-        body = request.get_json(force=True) or {}
-        folder_path = body.get("folderPath") or None
-        agent_id = body.get("agentId") or None
-        res = functions.dedup_folder_observations(_get_kv(), folder_path, agent_id)
-        return jsonify(res), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
-
-
-# ---------------------------------------------------------------------------
-# GET /agentmemory/observations  (legacy compat shim)
-# ---------------------------------------------------------------------------
-
-
-@observations_bp.route("/agentcache/observations", methods=["GET"])
-@observations_bp.route("/agentmemory/observations", methods=["GET"])
-def api_observations_legacy():
-    """Legacy /observations?sessionId=... shim.
-    Reads from legacy KV scope if data exists, otherwise returns empty list.
-    """
-    auth_err = _check_auth()
-    if auth_err:
-        return auth_err
-
-    session_id = request.args.get("sessionId", "")
-    if not session_id:
-        return jsonify({"observations": [], "sessionId": ""}), 200
-
-    try:
-        obs = sorted(
-            _get_kv().list(functions.KV.observations(session_id)),
-            key=lambda x: x.get("timestamp", ""),
-            reverse=True,
+    @bp.route("/agentcache/session/end", methods=["POST"])
+    @bp.route("/agentmemory/session/end", methods=["POST"])
+    def api_session_end():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+        return (
+            jsonify({"success": True, "message": "Session model is now folder-based."}),
+            200,
         )
-        return jsonify({"observations": obs, "sessionId": session_id}), 200
-    except Exception as e:
-        return jsonify(
-            {"observations": [], "sessionId": session_id, "error": str(e)}
-        ), 200
+
+    @bp.route("/agentcache/folder/dedup", methods=["POST"])
+    @bp.route("/agentmemory/folder/dedup", methods=["POST"])
+    def api_folder_dedup():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+        try:
+            body = request.get_json(force=True) or {}
+            folder_path = body.get("folderPath") or None
+            agent_id = body.get("agentId") or None
+            res = get_store().dedup(folder_path, agent_id)
+            return jsonify(res), 200
+        except Exception as e:
+            return jsonify({"error": str(e)}), 400
+
+    @bp.route("/agentcache/observations", methods=["GET"])
+    @bp.route("/agentmemory/observations", methods=["GET"])
+    def api_observations_legacy():
+        auth_err = _check_auth()
+        if auth_err:
+            return auth_err
+
+        session_id = request.args.get("sessionId", "")
+        if not session_id:
+            return jsonify({"observations": [], "sessionId": ""}), 200
+
+        try:
+            obs = sorted(
+                get_kv().list(KV.observations(session_id)),
+                key=lambda x: x.get("timestamp", ""),
+                reverse=True,
+            )
+            return jsonify({"observations": obs, "sessionId": session_id}), 200
+        except Exception as e:
+            return (
+                jsonify({"observations": [], "sessionId": session_id, "error": str(e)}),
+                200,
+            )
+
+    return bp
+
+
+observations_bp = create_observations_bp()

src/agentcache/routes/search.py

@@ -10,8 +10,6 @@ import os
 
 from flask import Blueprint, jsonify, request
 
-from .. import functions
-
 search_bp = Blueprint("search", __name__)
 
 
@@ -36,6 +34,18 @@ def _get_kv():
     return app_module.kv
 
 
+def _get_search_service():
+    from .. import app as app_module
+
+    return app_module.search_service
+
+
+def _get_observation_store():
+    from .. import app as app_module
+
+    return app_module.observation_store
+
+
 # ---------------------------------------------------------------------------
 # POST /agentcache/search
 # ---------------------------------------------------------------------------
@@ -57,9 +67,17 @@ def api_search():
         folder_path = body.get("folderPath")
         agent_id = body.get("agentId")
 
-        res = functions.folder_search(
-            _get_kv(), query, limit, folder_path=folder_path, agent_id=agent_id
-        )
+        search_svc = _get_search_service()
+        if search_svc is not None:
+            res = search_svc.search(
+                query=query,
+                limit=limit,
+                folder_path=folder_path,
+                agent_id=agent_id,
+                kv=_get_kv(),
+            )
+        else:
+            res = []
         return jsonify(res), 200
     except Exception as e:
         return jsonify({"error": str(e)}), 400
@@ -84,9 +102,17 @@ def api_timeline():
         limit = body.get("limit") or 100
         before = body.get("before")
         after = body.get("after")
-        result = functions.folder_timeline(
-            _get_kv(), limit, folder_path, agent_id, before, after
-        )
+        obs_store = _get_observation_store()
+        if obs_store is not None:
+            result = obs_store.timeline(
+                limit=limit,
+                folder_path=folder_path,
+                agent_id=agent_id,
+                before=before,
+                after=after,
+            )
+        else:
+            result = []
         return jsonify({"observations": result}), 200
     except Exception as e:
         return jsonify({"error": str(e)}), 400

src/agentcache/search.py

@@ -522,6 +522,7 @@ class SearchIndex:
         parts = [
             obs.get("title", ""),
             obs.get("subtitle", "") or "",
+            obs.get("text", "") or "",
             obs.get("narrative", "") or "",
             " ".join(obs.get("facts", []) or []),
             " ".join(obs.get("concepts", []) or []),

src/agentcache/storage/scopes.py

@@ -1,78 +1,9 @@
 """
 src/storage/scopes.py — KV scope registry (A2.3).
 
-Copied from src/functions.py — do NOT delete the original (backward compat).
-The KV class defines all storage scope keys used across agentcache-python.
+Re-exports KV from core.kv_scopes for backward compatibility.
 """
 
+from ..core.kv_scopes import KV
 
-class KV:
-    # ---- Folder memory scopes (new) ----
-
-    # Global index of all (folder_path, agent_id) pairs known to the system.
-    # Key = "{safe_folder_path}:{agent_id}", value = FolderIndexEntry dict.
-    folders = "mem:folders"
-
-    @staticmethod
-    def folder_obs(folder_path: str, agent_id: str) -> str:
-        """Per-(folder, agent) observations scope.
-        Key = obs_id, value = FolderObservation dict.
-        """
-        safe_path = folder_path.replace("\\", "/").strip("/")
-        safe_agent = agent_id.strip()
-        return f"mem:folder:{safe_path}:{safe_agent}"
-
-    @staticmethod
-    def folder_meta(folder_path: str, agent_id: str) -> str:
-        """Per-(folder, agent) metadata scope.
-        Key = "meta", value = FolderMeta dict (obsCount, lastUpdated, summary).
-        """
-        safe_path = folder_path.replace("\\", "/").strip("/")
-        safe_agent = agent_id.strip()
-        return f"mem:foldermeta:{safe_path}:{safe_agent}"
-
-    @staticmethod
-    def obs_dedup(folder_path: str, agent_id: str) -> str:
-        """Deduplication index scope for (folder, agent) pairs.
-        Key = SHA-256 fingerprint hex of normalized text.
-        Value = {"obsId": str, "timestamp": str}
-        """
-        safe_path = folder_path.replace("\\", "/").strip("/")
-        safe_agent = agent_id.strip()
-        return f"mem:obs_dedup:{safe_path}:{safe_agent}"
-
-    # ---- Global / shared scopes (kept) ----
-
-    # Long-term memories — unchanged from previous implementation.
-    memories = "mem:memories"
-
-    # BM25 index shards — unchanged.
-    bm25Index = "mem:index:bm25"
-
-    # Audit log — unchanged.
-    audit = "mem:audit"
-
-    # Graph edges — repurposed for folder graph edges.
-    relations = "mem:relations"
-
-    # ---- Legacy scopes (read-only; kept for migration and backward compat) ----
-
-    # Legacy session store — read by migrate_sessions_to_folders() and legacy observe().
-    sessions = "mem:sessions"
-
-    @staticmethod
-    def observations(session_id: str) -> str:
-        """Legacy per-session observations scope.
-        Key = obs_id, value = raw/synthetic observation dict.
-        Read by migrate_sessions_to_folders() and legacy observe().
-        """
-        return f"mem:obs:{session_id}"
-
-    # Legacy summary / profile / slot / image-ref scopes retained for legacy code paths.
-    summaries = "mem:summaries"
-    profiles = "mem:profiles"
-    slots = "mem:slots"
-    imageRefs = "mem:image-refs"
-
-    # Global (cross-project) pinned slots.
-    globalSlots = "mem:global-slots"
+__all__ = ["KV"]

src/agentcache/workers.py

@@ -14,14 +14,14 @@ import sys
 import threading
 import time
 
-from . import functions
+from . import legacy
 
 # Module-level shutdown flag — set by signal handlers
 _shutting_down = threading.Event()
 
-# Reference to the persistence object (set by start_background_workers)
 _persistence_ref = None
-# Reference to the kv object (set by start_background_workers)
+_search_svc_ref = None
+_obs_store_ref = None
 _kv_ref = None
 
 
@@ -30,7 +30,7 @@ def _shutdown_handler(signum, frame) -> None:  # noqa: ARG001
 
     Steps:
     1. Set the global _shutting_down flag to stop background loops.
-    2. Flush the debounce timer and save the index synchronously.
+    2. Flush the debounce timer and save the index synchronously via SearchService.flush_persist().
     3. Run a WAL checkpoint via StateKV.teardown().
     4. Exit cleanly with code 0.
     """
@@ -39,9 +39,15 @@ def _shutdown_handler(signum, frame) -> None:  # noqa: ARG001
 
     _shutting_down.set()
 
-    # Flush in-flight persistence debounce timer and save immediately
-    global _persistence_ref
-    if _persistence_ref is not None:
+    global _search_svc_ref, _persistence_ref
+    if _search_svc_ref is not None:
+        try:
+            print("[workers] Flushing SearchService persistence...")
+            _search_svc_ref.flush_persist()
+            print("[workers] SearchService persistence flushed.")
+        except Exception as e:
+            print(f"[workers] Error flushing SearchService: {e}")
+    elif _persistence_ref is not None:
         try:
             print("[workers] Flushing index persistence...")
             _persistence_ref.flush()
@@ -89,7 +95,7 @@ def _auto_forget_loop(kv) -> None:
                 if kv.acquire_lock("auto_forget", lease_seconds=300):
                     try:
                         print("[scheduler] Running auto_forget sweep...")
-                        res = functions.auto_forget(kv, dry_run=False)
+                        res = legacy.auto_forget(kv, dry_run=False)
                         print(f"[scheduler] auto_forget sweep completed: {res}")
                     finally:
                         kv.release_lock("auto_forget")
@@ -107,7 +113,13 @@ def _rebuild_index(kv) -> None:
     try:
         if kv.acquire_lock("index_rebuild", lease_seconds=600):
             try:
-                count = functions.rebuild_index(kv)
+                from . import app as app_module
+
+                obs_store = getattr(app_module, "observation_store", None)
+                if obs_store is not None:
+                    count = obs_store.rebuild_index()
+                else:
+                    count = 0
                 print(f"[persistence] Rebuild completed: indexed {count} items.")
             finally:
                 kv.release_lock("index_rebuild")
@@ -127,21 +139,34 @@ def start_background_workers(kv, tasks=None) -> None:
         kv: Initialised StateKV instance.
         tasks: Optional list of tasks to run ("index", "forget"). Defaults to running both.
     """
-    global _kv_ref, _persistence_ref
+    global _kv_ref, _persistence_ref, _search_svc_ref, _obs_store_ref
     _kv_ref = kv
 
-    # Capture the persistence reference for the shutdown handler
-    _persistence_ref = functions._index_persistence
+    from . import app as app_module
+
+    search_svc = getattr(app_module, "search_service", None)
+    obs_store = getattr(app_module, "observation_store", None)
+
+    _search_svc_ref = search_svc
+    _obs_store_ref = obs_store
+
+    if search_svc is not None:
+        _persistence_ref = search_svc._persistence
+    else:
+        _persistence_ref = None
 
     # Register graceful shutdown signal handlers (C5.1)
     _register_signal_handlers()
 
     if tasks is None or "index" in tasks:
         # Rebuild search index if empty or out of sync (Step 5)
-        index_empty = functions._bm25_index.size == 0
+        bm25_size = search_svc.bm25_size if search_svc is not None else 0
+        index_empty = bm25_size == 0
         index_in_sync = True
         if not index_empty:
-            index_in_sync = functions.verify_index_sync_on_boot(kv)
+            index_in_sync = legacy.verify_index_sync_on_boot(
+                kv, search_service=search_svc
+            )
 
         if index_empty or not index_in_sync:
             reason = "empty" if index_empty else "out of sync"

tests/__init__.py

@@ -1,2 +0,0 @@
-# tests package
-

tests/conftest.py

@@ -3,6 +3,7 @@ Shared pytest fixtures for agentcache test suite.
 """
 
 import pytest
+
 import agentcache.app as app_mod
 from agentcache.app import create_app
 from agentcache.db import StateKV

tests/test_api.py

@@ -1,294 +0,0 @@
-"""
-tests/test_api.py — C3.1
-
-Integration tests for REST endpoints using the Flask test client.
-"""
-
-import datetime
-import json
-import os
-
-import pytest
-
-# ---------------------------------------------------------------------------
-# Fixtures
-# ---------------------------------------------------------------------------
-
-
-@pytest.fixture(scope="module")
-def flask_app(tmp_path_factory):
-    tmp_dir = tmp_path_factory.mktemp("api_test_db")
-    db_path = str(tmp_dir / "test.db")
-    os.environ.pop("AGENTCACHE_SECRET", None)
-    os.environ.pop("AGENTMEMORY_SECRET", None)
-
-    from agentcache.db import StateKV
-
-    original_init = StateKV.__init__
-
-    def patched_init(self, db_path_arg=None, **kwargs):
-        original_init(self, db_path=db_path, **kwargs)
-
-    StateKV.__init__ = patched_init
-    import agentcache.app as app_module
-
-    os.environ.pop("AGENTCACHE_SECRET", None)
-    os.environ.pop("AGENTMEMORY_SECRET", None)
-    flask_application = app_module.create_app()
-    StateKV.__init__ = original_init
-    flask_application.config["TESTING"] = True
-    return flask_application
-
-
-@pytest.fixture(scope="module")
-def client(flask_app):
-    return flask_app.test_client()
-
-
-def _now():
-    return (
-        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
-    )
-
-
-def _post(client, url, payload):
-    return client.post(url, data=json.dumps(payload), content_type="application/json")
-
-
-# ---------------------------------------------------------------------------
-# POST /agentcache/agent/observe
-# ---------------------------------------------------------------------------
-
-
-class TestAgentObserve:
-    def test_valid_payload_returns_201(self, client):
-        resp = _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "folderPath": "/home/user/test-project",
-                "agentId": "kiro",
-                "text": "Implemented new authentication middleware",
-                "timestamp": _now(),
-            },
-        )
-        assert resp.status_code == 201
-        data = resp.get_json()
-        assert "observationId" in data
-        assert data["observationId"].startswith("fobs_")
-
-    def test_missing_folder_path_returns_400(self, client):
-        resp = _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "agentId": "kiro",
-                "text": "Some work",
-                "timestamp": _now(),
-            },
-        )
-        assert resp.status_code == 400
-
-    def test_missing_agent_id_returns_400(self, client):
-        resp = _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "folderPath": "/home/user/proj",
-                "text": "Some work",
-                "timestamp": _now(),
-            },
-        )
-        assert resp.status_code == 400
-
-    def test_missing_text_returns_400(self, client):
-        resp = _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "folderPath": "/home/user/proj",
-                "agentId": "kiro",
-                "timestamp": _now(),
-            },
-        )
-        assert resp.status_code == 400
-
-
-# ---------------------------------------------------------------------------
-# POST /agentcache/search
-# ---------------------------------------------------------------------------
-
-
-class TestSearch:
-    def test_search_with_query_returns_200(self, client):
-        # Seed data first
-        _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "folderPath": "/home/user/search-proj",
-                "agentId": "kiro",
-                "text": "Refactored the authentication system",
-                "timestamp": _now(),
-            },
-        )
-        resp = _post(client, "/agentcache/search", {"query": "authentication"})
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert isinstance(data, list) or isinstance(data, dict)
-
-    def test_search_missing_query_returns_400(self, client):
-        resp = _post(client, "/agentcache/search", {})
-        assert resp.status_code == 400
-
-    def test_search_empty_query_returns_400(self, client):
-        resp = _post(client, "/agentcache/search", {"query": "   "})
-        assert resp.status_code == 400
-
-
-# ---------------------------------------------------------------------------
-# GET /agentcache/folders
-# ---------------------------------------------------------------------------
-
-
-class TestFolders:
-    def test_get_folders_returns_200(self, client):
-        # Ensure at least one folder exists from earlier tests
-        _post(
-            client,
-            "/agentcache/agent/observe",
-            {
-                "folderPath": "/home/user/folders-check",
-                "agentId": "kiro",
-                "text": "Check folders endpoint",
-                "timestamp": _now(),
-            },
-        )
-        resp = client.get("/agentcache/folders")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert "folders" in data
-        assert isinstance(data["folders"], list)
-
-
-# ---------------------------------------------------------------------------
-# GET /agentcache/health
-# ---------------------------------------------------------------------------
-
-
-class TestHealth:
-    def test_health_returns_200(self, client):
-        resp = client.get("/agentcache/health")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert "folderCount" in data
-        assert "observationCount" in data
-        assert "memoryCount" in data
-
-    def test_health_status_ok(self, client):
-        resp = client.get("/agentcache/health")
-        data = resp.get_json()
-        assert data.get("status") in ("ok", "degraded")
-
-
-# ---------------------------------------------------------------------------
-# GET /agentcache/livez
-# ---------------------------------------------------------------------------
-
-
-class TestLivez:
-    def test_livez_returns_200_no_auth(self, client):
-        resp = client.get("/agentcache/livez")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert data["status"] == "ok"
-
-    def test_livez_open_with_secret_set(self, client):
-        os.environ["AGENTCACHE_SECRET"] = "test-secret-123"
-        try:
-            resp = client.get("/agentcache/livez")
-            assert resp.status_code == 200
-        finally:
-            del os.environ["AGENTCACHE_SECRET"]
-
-
-# ---------------------------------------------------------------------------
-# Authentication
-# ---------------------------------------------------------------------------
-
-
-class TestAuthentication:
-    def test_protected_endpoint_returns_401_with_wrong_token(self, client):
-        os.environ["AGENTCACHE_SECRET"] = "correct-secret"
-        try:
-            resp = client.get(
-                "/agentcache/audit",
-                headers={"Authorization": "Bearer wrong-token"},
-            )
-            assert resp.status_code == 401
-        finally:
-            del os.environ["AGENTCACHE_SECRET"]
-
-    def test_protected_endpoint_passes_with_correct_token(self, client):
-        secret = "my-test-secret-xyz"
-        os.environ["AGENTCACHE_SECRET"] = secret
-        try:
-            resp = client.get(
-                "/agentcache/audit",
-                headers={"Authorization": f"Bearer {secret}"},
-            )
-            assert resp.status_code == 200
-        finally:
-            del os.environ["AGENTCACHE_SECRET"]
-
-    def test_livez_always_open_regardless_of_secret(self, client):
-        os.environ["AGENTCACHE_SECRET"] = "any-secret"
-        try:
-            resp = client.get("/agentcache/livez")
-            assert resp.status_code == 200
-        finally:
-            del os.environ["AGENTCACHE_SECRET"]
-
-
-# ---------------------------------------------------------------------------
-# Additional endpoint smoke tests
-# ---------------------------------------------------------------------------
-
-
-class TestMemoriesEndpoint:
-    def test_memories_list_returns_200(self, client):
-        resp = client.get("/agentcache/memories")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert "memories" in data
-
-    def test_remember_valid_payload_returns_201(self, client):
-        resp = _post(
-            client,
-            "/agentcache/remember",
-            {
-                "content": "API test memory content",
-                "type": "fact",
-            },
-        )
-        assert resp.status_code == 201
-
-    def test_forget_nonexistent_id(self, client):
-        resp = _post(client, "/agentcache/forget", {"memoryId": "mem_nonexistent"})
-        assert resp.status_code == 200
-
-    def test_graph_endpoint_returns_200(self, client):
-        resp = client.get("/agentcache/graph")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert "nodes" in data
-        assert "edges" in data
-
-    def test_mcp_tools_list_returns_200(self, client):
-        resp = client.get("/agentcache/mcp/tools")
-        assert resp.status_code == 200
-        data = resp.get_json()
-        assert "tools" in data
-        tool_names = {t["name"] for t in data["tools"]}
-        assert "agent_observe" in tool_names
-        assert "cache_recall" in tool_names

tests/test_auth.py

@@ -3,8 +3,8 @@ Unit and integration tests for authentication and authorization.
 """
 
 from flask import Flask, jsonify
-from agentcache.routes.auth import require_auth, verify_token
 
+from agentcache.routes.auth import require_auth, verify_token
 
 # ------------------------------------------------------------------------------
 # Unit Tests — verify_token & require_auth
@@ -85,7 +85,11 @@ def test_protected_routes_require_auth(authed_client):
     headers = {"Authorization": f"Bearer {secret}"}
 
     protected_endpoints = [
-        ("POST", "/agentcache/observe", {"folderPath": "src/test", "agentId": "a1", "text": "test"}),
+        (
+            "POST",
+            "/agentcache/observe",
+            {"folderPath": "src/test", "agentId": "a1", "text": "test"},
+        ),
         ("POST", "/agentcache/remember", {"content": "test memory"}),
         ("POST", "/agentcache/search", {"query": "test"}),
         ("POST", "/agentcache/timeline", {}),
@@ -104,8 +108,12 @@ def test_protected_routes_require_auth(authed_client):
             res_unauth = client.get(path)
             res_auth = client.get(path, headers=headers)
 
-        assert res_unauth.status_code == 401, f"{method} {path} should require auth (got {res_unauth.status_code})"
-        assert res_auth.status_code in (200, 201), f"{method} {path} failed with valid auth (got {res_auth.status_code})"
+        assert res_unauth.status_code == 401, (
+            f"{method} {path} should require auth (got {res_unauth.status_code})"
+        )
+        assert res_auth.status_code in (200, 201), (
+            f"{method} {path} failed with valid auth (got {res_auth.status_code})"
+        )
 
 
 def test_unprotected_routes_accessible_without_auth(authed_client):
@@ -120,7 +128,9 @@ def test_unprotected_routes_accessible_without_auth(authed_client):
 
     for path in unprotected_paths:
         res = client.get(path)
-        assert res.status_code == 200, f"Unprotected route {path} failed (got {res.status_code})"
+        assert res.status_code == 200, (
+            f"Unprotected route {path} failed (got {res.status_code})"
+        )
 
 
 def test_wrong_token_on_any_blueprint_returns_401(authed_client):
@@ -129,7 +139,11 @@ def test_wrong_token_on_any_blueprint_returns_401(authed_client):
     bad_headers = {"Authorization": "Bearer wrong-token-value"}
 
     protected_endpoints = [
-        ("POST", "/agentcache/observe", {"folderPath": "src/test", "agentId": "a1", "text": "test"}),
+        (
+            "POST",
+            "/agentcache/observe",
+            {"folderPath": "src/test", "agentId": "a1", "text": "test"},
+        ),
         ("POST", "/agentcache/remember", {"content": "test memory"}),
         ("POST", "/agentcache/search", {"query": "test"}),
         ("POST", "/agentcache/timeline", {}),
@@ -139,7 +153,6 @@ def test_wrong_token_on_any_blueprint_returns_401(authed_client):
         ("POST", "/agentcache/migrate", {}),
     ]
 
-
     for method, path, payload in protected_endpoints:
         if method == "POST":
             res = client.post(path, json=payload or {}, headers=bad_headers)

tests/test_auto_forget.py

@@ -1,139 +0,0 @@
-"""Unit tests for auto_forget() folder-based and memory-based eviction."""
-
-import datetime
-import os
-
-from agentcache.db import StateKV
-from agentcache.functions import KV, auto_forget, folder_observe, remember
-
-
-def make_kv(tmp_path):
-    db_path = os.path.join(str(tmp_path), "test.db")
-    return StateKV(db_path=db_path)
-
-
-def test_auto_forget_memories(tmp_path):
-    kv = make_kv(tmp_path)
-
-    # 1. Create a memory that expires in the past
-    past_time = (
-        (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=1))
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-    res1 = remember(kv, {"content": "Stale memory", "forgetAfter": past_time})
-    mem1_id = res1["memory"]["id"]
-
-    # 2. Create a memory that expires in the future
-    future_time = (
-        (datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=5))
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-    res2 = remember(kv, {"content": "Fresh memory", "forgetAfter": future_time})
-    mem2_id = res2["memory"]["id"]
-
-    # Run auto_forget
-    results = auto_forget(kv, dry_run=False)
-    assert len(results["evictedMemories"]) == 1
-
-    # Verify mem1 is deleted, mem2 exists
-    assert kv.get(KV.memories, mem1_id) is None
-    assert kv.get(KV.memories, mem2_id) is not None
-
-
-def test_auto_forget_expired_folder_observations(tmp_path):
-    kv = make_kv(tmp_path)
-    folder = "/home/user/myproject"
-    agent = "kiro"
-
-    # 1. Create expired folder observation
-    past_time = (
-        (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=1))
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-    res1 = folder_observe(
-        kv,
-        {
-            "folderPath": folder,
-            "agentId": agent,
-            "text": "Stale observation",
-            "timestamp": past_time,
-            "forgetAfter": past_time,
-        },
-    )
-    obs1_id = res1["observationId"]
-
-    # 2. Create fresh folder observation
-    future_time = (
-        (datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(days=1))
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-    res2 = folder_observe(
-        kv,
-        {
-            "folderPath": folder,
-            "agentId": agent,
-            "text": "Fresh observation",
-            "timestamp": past_time,
-            "forgetAfter": future_time,
-        },
-    )
-    obs2_id = res2["observationId"]
-
-    # Run auto_forget
-    results = auto_forget(kv, dry_run=False)
-    assert len(results["evictedObservations"]) == 1
-
-    # Verify eviction
-    fp = "home/user/myproject"
-    assert kv.get(KV.folder_obs(fp, agent), obs1_id) is None
-    assert kv.get(KV.folder_obs(fp, agent), obs2_id) is not None
-
-
-def test_auto_forget_low_importance_stale_observations(tmp_path):
-    kv = make_kv(tmp_path)
-    folder = "/home/user/myproject"
-    agent = "kiro"
-
-    # 1. Create old low-importance folder observation (importance = 1, 200 days old)
-    old_time = (
-        (datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=200))
-        .isoformat()
-        .replace("+00:00", "Z")
-    )
-    res1 = folder_observe(
-        kv,
-        {
-            "folderPath": folder,
-            "agentId": agent,
-            "text": "Stale low value observation",
-            "timestamp": old_time,
-            "importance": 1,
-        },
-    )
-    obs1_id = res1["observationId"]
-
-    # 2. Create old high-importance folder observation (importance = 8, 200 days old)
-    res2 = folder_observe(
-        kv,
-        {
-            "folderPath": folder,
-            "agentId": agent,
-            "text": "Stale high value observation",
-            "timestamp": old_time,
-            "importance": 8,
-        },
-    )
-    obs2_id = res2["observationId"]
-
-    # Run auto_forget
-    results = auto_forget(kv, dry_run=False)
-    assert len(results["evictedObservations"]) == 1
-
-    # Verify eviction
-    fp = "home/user/myproject"
-    assert kv.get(KV.folder_obs(fp, agent), obs1_id) is None
-    assert kv.get(KV.folder_obs(fp, agent), obs2_id) is not None

tests/test_cli_context.py

@@ -1,70 +0,0 @@
-"""Unit tests for the agentcache context CLI command."""
-
-import argparse
-import os
-from unittest.mock import patch
-
-from agentcache.cli import cmd_context
-from agentcache.db import StateKV
-from agentcache.functions import folder_observe, remember
-
-
-def make_kv(tmp_path):
-    db_path = os.path.join(str(tmp_path), "test.db")
-    return StateKV(db_path=db_path)
-
-
-def test_cli_context_generation(tmp_path):
-    kv = make_kv(tmp_path)
-
-    # 1. Add observations and memories
-    folder = "/home/user/myproject"
-    agent = "test-agent"
-
-    folder_observe(
-        kv,
-        {
-            "folderPath": folder,
-            "agentId": agent,
-            "text": "First observation",
-            "timestamp": "2026-07-15T10:00:00Z",
-        },
-    )
-
-    remember(
-        kv, {"content": "A crucial project rule", "type": "fact", "agentId": agent}
-    )
-
-    remember(
-        kv,
-        {
-            "content": "A project-wide memory",
-            "type": "architecture",
-            "project": "myproject",
-            "agentId": "some-other-agent",
-        },
-    )
-
-    output_file = os.path.join(str(tmp_path), "context.md")
-    args = argparse.Namespace(agent=agent, output=output_file, watch=False)
-
-    # Mock os.getcwd to match the project path and init_services to return our test db
-    with (
-        patch("os.getcwd", return_value=folder),
-        patch("agentcache.app.init_services", return_value=(kv, None, None)),
-    ):
-        cmd_context(args)
-
-    # 2. Verify file output
-    assert os.path.exists(output_file)
-    with open(output_file, "r", encoding="utf-8") as f:
-        content = f.read()
-
-    # Check that metadata and values are written
-    assert "Agent Cache Context" in content
-    assert "Project Metadata" in content
-    assert "myproject" in content
-    assert "test-agent" in content
-    assert "First observation" in content
-    assert "A crucial project rule" in content
-    assert "A project-wide memory" in content

tests/test_context.py

@@ -1,204 +0,0 @@
-"""
-tests/test_context.py — C1.4
-
-Tests for context(), export_data(), and token budget enforcement.
-"""
-
-import datetime
-import os
-
-import pytest
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-
-def _make_kv(tmp_path):
-    from agentcache.db import StateKV
-
-    os.environ.pop("AGENTCACHE_SECRET", None)
-    return StateKV(db_path=str(tmp_path / "test.db"))
-
-
-def _now():
-    return (
-        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
-    )
-
-
-# ---------------------------------------------------------------------------
-# context() tests
-# ---------------------------------------------------------------------------
-
-
-class TestContext:
-    def test_empty_db_returns_minimal_context(self, tmp_path):
-        """Empty DB should return a well-formed but empty context."""
-        from agentcache.functions import context
-
-        kv = _make_kv(tmp_path)
-        result = context(
-            kv,
-            {
-                "sessionId": "sess_test_empty",
-                "project": "/home/user/my-project",
-                "budget": 2000,
-            },
-        )
-        assert isinstance(result, dict)
-        assert "context" in result
-        assert "blocks" in result
-        assert "tokens" in result
-        assert result["blocks"] == 0
-        assert result["tokens"] == 0
-
-    def test_raises_on_missing_session_id(self, tmp_path):
-        from agentcache.functions import context
-
-        kv = _make_kv(tmp_path)
-        with pytest.raises(ValueError):
-            context(kv, {"project": "/home/user/proj"})
-
-    def test_raises_on_missing_project(self, tmp_path):
-        from agentcache.functions import context
-
-        kv = _make_kv(tmp_path)
-        with pytest.raises(ValueError):
-            context(kv, {"sessionId": "sess_x"})
-
-    def test_respects_token_budget(self, tmp_path):
-        """Context output tokens should not exceed the requested budget."""
-        from agentcache.functions import context, lesson_save
-
-        kv = _make_kv(tmp_path)
-        project = "/home/user/budget-test"
-
-        # Add many lessons to push towards the budget
-        for i in range(20):
-            lesson_save(
-                kv,
-                {
-                    "content": f"Lesson {i}: " + ("x " * 100),
-                    "project": project,
-                    "confidence": 0.9,
-                },
-            )
-
-        budget = 500
-        result = context(
-            kv,
-            {
-                "sessionId": "sess_budget",
-                "project": project,
-                "budget": budget,
-            },
-        )
-        # Token estimate is len/3 — check that total tokens respects budget
-        assert result["tokens"] <= budget + 50  # small headroom for header/footer
-
-    def test_context_includes_xml_wrapper(self, tmp_path):
-        """Non-empty context should be wrapped in <agentcache-context>."""
-        from agentcache.functions import context, lesson_save
-
-        kv = _make_kv(tmp_path)
-        project = "/home/user/xml-test"
-
-        lesson_save(
-            kv,
-            {
-                "content": "Always validate user input before processing",
-                "project": project,
-                "confidence": 0.8,
-            },
-        )
-
-        result = context(
-            kv,
-            {
-                "sessionId": "sess_xml",
-                "project": project,
-                "budget": 2000,
-            },
-        )
-
-        if result["blocks"] > 0:
-            assert "<agentcache-context" in result["context"]
-            assert "</agentcache-context>" in result["context"]
-
-    def test_token_budget_env_var_respected(self, tmp_path, monkeypatch):
-        """TOKEN_BUDGET env var should be used when no budget param given."""
-        from agentcache.functions import context, lesson_save
-
-        kv = _make_kv(tmp_path)
-        project = "/home/user/env-budget"
-        monkeypatch.setenv("TOKEN_BUDGET", "100")
-
-        for i in range(10):
-            lesson_save(
-                kv,
-                {
-                    "content": f"Important lesson {i}: " + ("word " * 50),
-                    "project": project,
-                    "confidence": 0.9,
-                },
-            )
-
-        result = context(kv, {"sessionId": "sess_env_budget", "project": project})
-        # Should use TOKEN_BUDGET=100 from env
-        assert result["tokens"] <= 150  # with some headroom for XML wrapper
-
-
-# ---------------------------------------------------------------------------
-# export_data() tests
-# ---------------------------------------------------------------------------
-
-
-class TestExportData:
-    def test_export_returns_folders_and_memories(self, tmp_path):
-        from agentcache.functions import export_data, folder_observe, remember
-
-        kv = _make_kv(tmp_path)
-
-        folder_observe(
-            kv,
-            {
-                "folderPath": "/home/user/export-test",
-                "agentId": "kiro",
-                "text": "Working on export feature",
-                "timestamp": _now(),
-            },
-        )
-        remember(kv, {"content": "Export data uses v2 format"})
-
-        result = export_data(kv, {})
-        assert isinstance(result, dict)
-        assert "folders" in result or "observations" in result or "memories" in result
-
-    def test_export_empty_db(self, tmp_path):
-        from agentcache.functions import export_data
-
-        kv = _make_kv(tmp_path)
-        result = export_data(kv, {})
-        assert isinstance(result, dict)
-        # Should not crash on empty DB
-
-
-# ---------------------------------------------------------------------------
-# estimate_tokens()
-# ---------------------------------------------------------------------------
-
-
-class TestEstimateTokens:
-    def test_empty_string(self):
-        from agentcache.functions import estimate_tokens
-
-        assert estimate_tokens("") == 0
-
-    def test_typical_text(self):
-        from agentcache.functions import estimate_tokens
-
-        text = "hello world this is a test" * 10
-        tokens = estimate_tokens(text)
-        # Should be approximately len/3
-        assert tokens == len(text) // 3

tests/test_debounce.py

@@ -1,166 +0,0 @@
-"""A4.3 — Unit tests for IndexPersistence debounce behavior.
-
-Tests:
-- 100 rapid schedule_save() calls result in exactly 1 save() call.
-- flush() triggers immediate save without waiting for debounce timer.
-"""
-
-import time
-import unittest.mock as mock
-
-from agentcache.db import StateKV
-from agentcache.functions import IndexPersistence
-from agentcache.search import SearchIndex, VectorIndex
-
-# Speed up debounce for tests
-FAST_DEBOUNCE = 0.05
-
-
-def make_kv(tmp_path):
-    return StateKV(db_path=str(tmp_path / "test_debounce.db"))
-
-
-class TestDebounce:
-    def test_100_rapid_calls_result_in_1_save(self, tmp_path):
-        """100 rapid schedule_save() calls must fire exactly 1 save()."""
-        kv = make_kv(tmp_path)
-        bm25 = SearchIndex()
-        vector = VectorIndex()
-
-        persistence = IndexPersistence(kv, bm25, vector)
-        persistence.DEBOUNCE_SECONDS = FAST_DEBOUNCE
-
-        save_call_count = [0]
-
-        original_save = persistence.save
-
-        def counting_save():
-            save_call_count[0] += 1
-            original_save()
-
-        with mock.patch.object(persistence, "save", side_effect=counting_save):
-            for _ in range(100):
-                persistence.schedule_save()
-            # Wait for the debounce timer to fire (2× debounce window is plenty)
-            time.sleep(FAST_DEBOUNCE * 4)
-
-        assert save_call_count[0] == 1, (
-            f"Expected exactly 1 save() call; got {save_call_count[0]}"
-        )
-
-    def test_rapid_calls_with_dirty_bm25(self, tmp_path):
-        """schedule_save() fires exactly once even when BM25 is dirty."""
-        kv = make_kv(tmp_path)
-        bm25 = SearchIndex()
-        vector = VectorIndex()
-
-        # Add a doc so the index is dirty
-        bm25.add(
-            {
-                "id": "obs_test1",
-                "sessionId": "sess1",
-                "title": "hello world",
-                "facts": [],
-                "concepts": [],
-                "files": [],
-                "type": "other",
-            }
-        )
-
-        persistence = IndexPersistence(kv, bm25, vector)
-        persistence.DEBOUNCE_SECONDS = FAST_DEBOUNCE
-
-        save_call_count = [0]
-        original_save = persistence.save
-
-        def counting_save():
-            save_call_count[0] += 1
-            original_save()
-
-        with mock.patch.object(persistence, "save", side_effect=counting_save):
-            for _ in range(100):
-                persistence.schedule_save()
-            time.sleep(FAST_DEBOUNCE * 4)
-
-        assert save_call_count[0] == 1
-
-    def test_flush_triggers_immediate_save(self, tmp_path):
-        """flush() must call save() immediately without waiting for the debounce timer."""
-        kv = make_kv(tmp_path)
-        bm25 = SearchIndex()
-        vector = VectorIndex()
-
-        persistence = IndexPersistence(kv, bm25, vector)
-        persistence.DEBOUNCE_SECONDS = 60.0  # very long timer — flush must bypass it
-
-        save_call_count = [0]
-        original_save = persistence.save
-
-        def counting_save():
-            save_call_count[0] += 1
-            original_save()
-
-        with mock.patch.object(persistence, "save", side_effect=counting_save):
-            persistence.schedule_save()
-            # Timer is set but hasn't fired yet (60s window)
-            assert save_call_count[0] == 0, "save() should not have been called yet"
-
-            # flush() must cancel the timer and call save() synchronously
-            persistence.flush()
-
-        assert save_call_count[0] == 1, (
-            f"flush() should trigger exactly 1 save(); got {save_call_count[0]}"
-        )
-
-    def test_flush_after_no_pending_save_is_safe(self, tmp_path):
-        """flush() with no pending timer should still call save() once."""
-        kv = make_kv(tmp_path)
-        bm25 = SearchIndex()
-        vector = VectorIndex()
-
-        persistence = IndexPersistence(kv, bm25, vector)
-
-        save_call_count = [0]
-        original_save = persistence.save
-
-        def counting_save():
-            save_call_count[0] += 1
-            original_save()
-
-        with mock.patch.object(persistence, "save", side_effect=counting_save):
-            persistence.flush()
-
-        assert save_call_count[0] == 1
-
-    def test_subsequent_schedule_after_fire_starts_new_timer(self, tmp_path):
-        """Two bursts of saves separated by more than DEBOUNCE_SECONDS should fire 2 saves."""
-        kv = make_kv(tmp_path)
-        bm25 = SearchIndex()
-        vector = VectorIndex()
-
-        persistence = IndexPersistence(kv, bm25, vector)
-        persistence.DEBOUNCE_SECONDS = FAST_DEBOUNCE
-
-        save_call_count = [0]
-        original_save = persistence.save
-
-        def counting_save():
-            save_call_count[0] += 1
-            original_save()
-
-        with mock.patch.object(persistence, "save", side_effect=counting_save):
-            # First burst
-            for _ in range(10):
-                persistence.schedule_save()
-            # Wait for first timer to fire
-            time.sleep(FAST_DEBOUNCE * 4)
-
-            # Second burst
-            for _ in range(10):
-                persistence.schedule_save()
-            # Wait for second timer to fire
-            time.sleep(FAST_DEBOUNCE * 4)
-
-        assert save_call_count[0] == 2, (
-            f"Expected 2 save() calls for two separate bursts; got {save_call_count[0]}"
-        )

tests/test_folder_graph_build.py

@@ -1,432 +0,0 @@
-"""Unit tests for folderColor() and folder_graph_build() — REQ-023–REQ-028."""
-
-import pytest
-
-from agentcache.db import StateKV
-from agentcache.functions import KV, folder_graph_build
-from agentcache.functions import folder_color as folderColor
-
-# ---------------------------------------------------------------------------
-# Fixtures
-# ---------------------------------------------------------------------------
-
-
-@pytest.fixture()
-def kv(tmp_path):
-    """Return a fresh in-file StateKV backed by a temp SQLite database."""
-    db_file = str(tmp_path / "test.db")
-    return StateKV(db_path=db_file)
-
-
-def _write_pair(
-    kv: StateKV,
-    folder_path: str,
-    agent_id: str,
-    obs_texts: list = None,
-    obs_count: int = None,
-) -> None:
-    """Insert a (folder_path, agent_id) entry into KV.folders and optionally write observations."""
-    obs_texts = obs_texts or []
-    count = obs_count if obs_count is not None else len(obs_texts)
-
-    # Write folders index entry
-    index_key = f"{folder_path}:{agent_id}"
-    kv.set(
-        KV.folders,
-        index_key,
-        {
-            "folderPath": folder_path,
-            "agentId": agent_id,
-            "obsCount": count,
-            "lastUpdated": "2025-01-15T12:00:00.000Z",
-        },
-    )
-
-    # Write observation objects if text supplied
-    for i, text in enumerate(obs_texts):
-        obs_id = f"obs_{folder_path.replace('/', '_')}_{agent_id}_{i}"
-        obs = {
-            "id": obs_id,
-            "folderPath": folder_path,
-            "agentId": agent_id,
-            "timestamp": "2025-01-15T12:00:00.000Z",
-            "text": text,
-            "type": "other",
-            "title": f"title {i}",
-            "concepts": [],
-            "files": [],
-            "importance": 5,
-        }
-        kv.set(KV.folder_obs(folder_path, agent_id), obs_id, obs)
-
-
-# ---------------------------------------------------------------------------
-# Tests — folderColor helper
-# ---------------------------------------------------------------------------
-
-
-def test_folder_color_returns_hsl_string():
-    """folderColor should return a string matching hsl(...) format."""
-    color = folderColor("projects/alpha")
-    assert color.startswith("hsl(")
-    assert color.endswith(")")
-
-
-def test_folder_color_deterministic():
-    """Same path always returns the same color."""
-    assert folderColor("projects/alpha") == folderColor("projects/alpha")
-
-
-def test_folder_color_different_paths_produce_different_colors():
-    """Different paths should (almost always) produce different colors."""
-    # Use very distinct paths to ensure hash difference
-    assert folderColor("projects/alpha") != folderColor(
-        "projects/omega-completely-different"
-    )
-
-
-def test_folder_color_hsl_values_in_range():
-    """HSL values should be within expected ranges."""
-    color = folderColor("some/path")
-    # Strip "hsl(" and ")" then parse
-    inner = color[4:-1]  # e.g. "200, 70%, 55%"
-    parts = [p.strip().rstrip("%") for p in inner.split(",")]
-    hue, sat, lig = int(parts[0]), int(parts[1]), int(parts[2])
-    assert 0 <= hue < 360
-    assert 55 <= sat <= 79  # 55 + (h % 25)
-    assert 38 <= lig <= 51  # 38 + (h % 14)
-
-
-def test_folder_color_empty_string():
-    """folderColor on empty string should not raise."""
-    color = folderColor("")
-    assert color.startswith("hsl(")
-
-
-# ---------------------------------------------------------------------------
-# Tests — empty KV returns empty graph (REQ-023)
-# ---------------------------------------------------------------------------
-
-
-def test_empty_kv_returns_empty_graph(kv):
-    """Empty KV returns {nodes: [], edges: []}."""
-    result = folder_graph_build(kv)
-    assert result == {"nodes": [], "edges": []}
-
-
-# ---------------------------------------------------------------------------
-# Tests — node construction (REQ-023, REQ-024)
-# ---------------------------------------------------------------------------
-
-
-def test_one_node_per_unique_folder_path(kv):
-    """Two agents in the same folder produce a single node (REQ-023)."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_count=3)
-    _write_pair(kv, "projects/alpha", "claude", obs_count=2)
-
-    result = folder_graph_build(kv)
-    assert len(result["nodes"]) == 1
-    node = result["nodes"][0]
-    assert node["folderPath"] == "projects/alpha"
-
-
-def test_multiple_folders_produce_multiple_nodes(kv):
-    """Each distinct folder_path produces exactly one node."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "kiro")
-    _write_pair(kv, "projects/gamma", "claude")
-
-    result = folder_graph_build(kv)
-    folder_paths = {n["folderPath"] for n in result["nodes"]}
-    assert folder_paths == {"projects/alpha", "projects/beta", "projects/gamma"}
-
-
-def test_node_fields_present(kv):
-    """Each node contains all required fields (REQ-024)."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_count=5)
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert "id" in node
-    assert "label" in node
-    assert "folderPath" in node
-    assert "agentIds" in node
-    assert "obsCount" in node
-    assert "color" in node
-
-
-def test_node_id_equals_folder_path(kv):
-    """Node id is the folderPath string."""
-    _write_pair(kv, "projects/alpha", "kiro")
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert node["id"] == "projects/alpha"
-    assert node["folderPath"] == "projects/alpha"
-
-
-def test_node_label_is_basename(kv):
-    """Node label is the last path component."""
-    _write_pair(kv, "home/user/projects/myapp", "kiro")
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert node["label"] == "myapp"
-
-
-def test_node_agent_ids_aggregated_and_sorted(kv):
-    """agentIds is the sorted union of all agents for that folder."""
-    _write_pair(kv, "projects/alpha", "zorro", obs_count=1)
-    _write_pair(kv, "projects/alpha", "alice", obs_count=1)
-    _write_pair(kv, "projects/alpha", "bob", obs_count=1)
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert node["agentIds"] == ["alice", "bob", "zorro"]
-
-
-def test_node_obs_count_summed_across_agents(kv):
-    """obsCount is the sum across all agents for that folder."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_count=4)
-    _write_pair(kv, "projects/alpha", "claude", obs_count=6)
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert node["obsCount"] == 10
-
-
-def test_node_color_is_hsl(kv):
-    """Node color comes from folderColor and is an HSL string."""
-    _write_pair(kv, "projects/alpha", "kiro")
-
-    result = folder_graph_build(kv)
-    node = result["nodes"][0]
-    assert node["color"].startswith("hsl(")
-    # Must match folderColor directly
-    assert node["color"] == folderColor("projects/alpha")
-
-
-# ---------------------------------------------------------------------------
-# Tests — same-parent edges (REQ-025)
-# ---------------------------------------------------------------------------
-
-
-def test_same_parent_edge_created(kv):
-    """Two folders with the same parent get a same-parent edge."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "kiro")  # both under "projects"
-
-    result = folder_graph_build(kv)
-    same_parent_edges = [e for e in result["edges"] if e["type"] == "same-parent"]
-    assert len(same_parent_edges) == 1
-    edge = same_parent_edges[0]
-    assert set([edge["source"], edge["target"]]) == {"projects/alpha", "projects/beta"}
-
-
-def test_no_same_parent_edge_for_different_parents(kv):
-    """Folders with different parents do not get a same-parent edge."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "work/beta", "kiro")
-
-    result = folder_graph_build(kv)
-    same_parent_edges = [e for e in result["edges"] if e["type"] == "same-parent"]
-    assert same_parent_edges == []
-
-
-def test_same_parent_edge_only_for_sharing_pairs(kv):
-    """Only pairs sharing a parent get same-parent edges; non-sharing pairs do not."""
-    _write_pair(kv, "a/x", "kiro")
-    _write_pair(kv, "a/y", "kiro")  # shares parent "a" with a/x
-    _write_pair(kv, "b/z", "kiro")  # different parent "b"
-
-    result = folder_graph_build(kv)
-    same_parent_edges = [e for e in result["edges"] if e["type"] == "same-parent"]
-    assert len(same_parent_edges) == 1
-    edge = same_parent_edges[0]
-    assert set([edge["source"], edge["target"]]) == {"a/x", "a/y"}
-
-
-# ---------------------------------------------------------------------------
-# Tests — cross-reference edges (REQ-026)
-# ---------------------------------------------------------------------------
-
-
-def test_cross_ref_edge_when_obs_mentions_other_folder(kv):
-    """A cross-ref edge is created when folder A's obs text mentions folder B's path."""
-    _write_pair(
-        kv, "projects/alpha", "kiro", obs_texts=["I worked on projects/beta today"]
-    )
-    _write_pair(kv, "projects/beta", "kiro", obs_texts=["nothing"])
-
-    result = folder_graph_build(kv)
-    cross_edges = [e for e in result["edges"] if e["type"] == "cross-ref"]
-    assert len(cross_edges) >= 1
-    sources_targets = {(e["source"], e["target"]) for e in cross_edges}
-    assert ("projects/alpha", "projects/beta") in sources_targets
-
-
-def test_no_cross_ref_edge_when_no_mention(kv):
-    """No cross-ref edge when obs texts don't mention another folder path."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_texts=["Just some work here"])
-    _write_pair(kv, "projects/beta", "kiro", obs_texts=["Unrelated content"])
-
-    result = folder_graph_build(kv)
-    cross_edges = [e for e in result["edges"] if e["type"] == "cross-ref"]
-    assert cross_edges == []
-
-
-def test_cross_ref_edge_from_title_mention(kv):
-    """Cross-ref edges are also detected via obs titles."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_texts=["some text"])
-    # Manually insert obs with a title that mentions the other folder
-    obs = {
-        "id": "obs_special",
-        "folderPath": "projects/alpha",
-        "agentId": "kiro",
-        "timestamp": "2025-01-15T12:00:00.000Z",
-        "text": "normal text",
-        "type": "other",
-        "title": "work on projects/beta",
-        "concepts": [],
-        "files": [],
-        "importance": 5,
-    }
-    kv.set(KV.folder_obs("projects/alpha", "kiro"), "obs_special", obs)
-    _write_pair(kv, "projects/beta", "kiro", obs_texts=["nothing"])
-
-    result = folder_graph_build(kv)
-    cross_edges = [e for e in result["edges"] if e["type"] == "cross-ref"]
-    sources = {e["source"] for e in cross_edges}
-    assert "projects/alpha" in sources
-
-
-# ---------------------------------------------------------------------------
-# Tests — agent-shared edges (REQ-027)
-# ---------------------------------------------------------------------------
-
-
-def test_agent_shared_edge_created(kv):
-    """Two folders with a common agent get an agent-shared edge."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "kiro")  # same agent "kiro"
-
-    result = folder_graph_build(kv)
-    agent_edges = [e for e in result["edges"] if e["type"] == "agent-shared"]
-    assert len(agent_edges) >= 1
-    edge = agent_edges[0]
-    assert set([edge["source"], edge["target"]]) == {"projects/alpha", "projects/beta"}
-
-
-def test_no_agent_shared_edge_when_no_common_agent(kv):
-    """Folders with no common agents do not get an agent-shared edge."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "claude")  # different agents
-
-    result = folder_graph_build(kv)
-    agent_edges = [e for e in result["edges"] if e["type"] == "agent-shared"]
-    assert agent_edges == []
-
-
-def test_agent_shared_edge_with_partial_overlap(kv):
-    """Two folders with one common agent among several agents still get an edge."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/alpha", "claude")
-    _write_pair(kv, "projects/beta", "claude")
-    _write_pair(kv, "projects/beta", "cursor")
-
-    result = folder_graph_build(kv)
-    agent_edges = [e for e in result["edges"] if e["type"] == "agent-shared"]
-    endpoints = {frozenset([e["source"], e["target"]]) for e in agent_edges}
-    assert frozenset({"projects/alpha", "projects/beta"}) in endpoints
-
-
-# ---------------------------------------------------------------------------
-# Tests — edge deduplication (REQ-028)
-# ---------------------------------------------------------------------------
-
-
-def test_no_duplicate_edges(kv):
-    """No two edges share the same (source, target, type) pair."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_texts=["mentions projects/beta"])
-    _write_pair(kv, "projects/beta", "kiro", obs_texts=["mentions projects/alpha"])
-
-    result = folder_graph_build(kv)
-    seen = set()
-    for edge in result["edges"]:
-        key = (frozenset([edge["source"], edge["target"]]), edge["type"])
-        assert key not in seen, f"Duplicate edge: {edge}"
-        seen.add(key)
-
-
-def test_ab_and_ba_treated_as_same_edge(kv):
-    """(a, b, type) and (b, a, type) are considered the same edge."""
-    # Both folders reference each other — should produce only one cross-ref edge
-    _write_pair(
-        kv, "projects/alpha", "kiro", obs_texts=["See also projects/beta for details"]
-    )
-    _write_pair(
-        kv, "projects/beta", "kiro", obs_texts=["Related to projects/alpha work"]
-    )
-
-    result = folder_graph_build(kv)
-    cross_edges = [e for e in result["edges"] if e["type"] == "cross-ref"]
-    # Should be exactly 1 cross-ref edge (not 2)
-    assert len(cross_edges) == 1
-
-
-def test_same_parent_and_agent_shared_are_separate_edge_types(kv):
-    """same-parent and agent-shared edges between the same pair are both kept."""
-    # Both folders share parent "projects" AND share agent "kiro"
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "kiro")
-
-    result = folder_graph_build(kv)
-    edge_types = {e["type"] for e in result["edges"]}
-    # We expect both types to appear
-    assert "same-parent" in edge_types
-    assert "agent-shared" in edge_types
-
-
-# ---------------------------------------------------------------------------
-# Tests — return structure
-# ---------------------------------------------------------------------------
-
-
-def test_return_has_nodes_and_edges_keys(kv):
-    """Result always has 'nodes' and 'edges' keys."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    result = folder_graph_build(kv)
-    assert "nodes" in result
-    assert "edges" in result
-
-
-def test_edge_has_required_fields(kv):
-    """Each edge has source, target, and type fields."""
-    _write_pair(kv, "projects/alpha", "kiro")
-    _write_pair(kv, "projects/beta", "kiro")
-
-    result = folder_graph_build(kv)
-    for edge in result["edges"]:
-        assert "source" in edge
-        assert "target" in edge
-        assert "type" in edge
-
-
-def test_single_folder_produces_no_edges(kv):
-    """A graph with only one folder produces no edges."""
-    _write_pair(kv, "projects/alpha", "kiro")
-
-    result = folder_graph_build(kv)
-    assert len(result["nodes"]) == 1
-    assert result["edges"] == []
-
-
-def test_edge_types_are_valid(kv):
-    """All edge types are one of the three valid values."""
-    _write_pair(kv, "projects/alpha", "kiro", obs_texts=["mentions projects/beta"])
-    _write_pair(kv, "projects/beta", "kiro")
-
-    result = folder_graph_build(kv)
-    valid_types = {"same-parent", "cross-ref", "agent-shared"}
-    for edge in result["edges"]:
-        assert edge["type"] in valid_types