feat: migrate agentmemory to agentcache namespace, endpoints, and tools

.clineskills

@@ -1,20 +1,19 @@
-# Agent Memory Rules
+# Agent Cache Rules
 
-This workspace is integrated with long-term semantic memory via `agentmemory-python`.
-You must act as your own memory manager by calling the memory MCP tools at critical boundaries.
+This workspace is integrated with long-term semantic memory via `agentcache-python`.
+You must act as your own memory manager by calling the cache MCP tools at critical boundaries.
 
 ## Rules & Workflow
 
 1. **Initial Search (Prefetch Context)**:
-   At the start of every session or new task, immediately call `memory_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
-   - Example: `memory_smart_search(query="jwt token rotation logic")`
+   At the start of every session or new task, immediately call `cache_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
+   - Example: `cache_smart_search(query="jwt token rotation logic")`
 
 2. **Lessons & Insights Capture**:
    When you successfully debug a complex error, discover an undocumented requirement, or establish a convention, persist it:
-   - Call `memory_lesson_save` to record lessons that improve your coding capabilities. Duplicate saves strengthen confidence scores.
-   - Call `memory_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
+   - Call `cache_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
 
 3. **Checklist Before Ending**:
    Before stating a task is complete:
-   - Reflect on whether any lessons learned should be saved.
-   - Call `memory_reflect` to automatically distribute observations into slots if needed.
+   - Reflect on whether any lessons learned or insights should be saved.
+   - Call `cache_dedup` to deduplicate any observations if needed.

.cursorrules

@@ -1,20 +1,23 @@
-# Agent Memory Rules
+# Agent Cache Rules
 
-This workspace is integrated with long-term semantic memory via `agentmemory-python`.
-You must act as your own memory manager by calling the memory MCP tools at critical boundaries.
+This workspace is integrated with long-term semantic memory via `agentcache-python`.
+You must act as your own memory manager by calling the cache MCP tools at critical boundaries.
 
 ## Rules & Workflow
 
 1. **Initial Search (Prefetch Context)**:
-   At the start of every session or new task, immediately call `memory_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
-   - Example: `memory_smart_search(query="jwt token rotation logic")`
+   At the start of every session or new task, immediately call `cache_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, and past work.
+   - Example: `cache_smart_search(query="jwt token rotation logic")`
 
-2. **Lessons & Insights Capture**:
+2. **Log Observations**:
+   As you work, call `agent_observe` to record what you are doing. Include `folderPath` (the working directory), `agentId` (your agent name), and `text` (what happened).
+   - Example: `agent_observe(folderPath="/your/project/path", agentId="cursor", text="Refactored auth middleware to use JWT rotation")`
+
+3. **Save Long-Term Memories**:
    When you successfully debug a complex error, discover an undocumented requirement, or establish a convention, persist it:
-   - Call `memory_lesson_save` to record lessons that improve your coding capabilities. Duplicate saves strengthen confidence scores.
-   - Call `memory_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
+   - Call `cache_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
 
-3. **Checklist Before Ending**:
+4. **Checklist Before Ending**:
    Before stating a task is complete:
-   - Reflect on whether any lessons learned should be saved.
-   - Call `memory_reflect` to automatically distribute observations into slots if needed.
+   - Reflect on whether any insights should be saved via `cache_save`.
+   - Review the folder activity feed with `cache_timeline` to confirm all significant work was captured.

.env.example

@@ -1,16 +1,16 @@
 # =============================================================================
-# agentmemory configuration
+# agentcache configuration
 # =============================================================================
 #
-# Copy this file to `~/.agentmemory/.env` (or to your project root if you
+# Copy this file to `~/.agentcache/.env` (or to your project root if you
 # prefer scoped config) and uncomment the lines you want to override.
 #
-# Every line is OFF by default — `agentmemory` runs out of the box with no
+# Every line is OFF by default — `agentcache` runs out of the box with no
 # LLM key, no embedding key, and no API auth. Set keys here only when you
 # want to enable the corresponding feature.
 #
-# Run `npx @agentmemory/agentmemory init` to copy this file into place
-# automatically. Run `npx @agentmemory/agentmemory doctor` to verify that
+# Run `npx @agentcache/agentcache init` to copy this file into place
+# automatically. Run `npx @agentcache/agentcache doctor` to verify that
 # the daemon reads the env you expect.
 #
 # Defaults shown in comments. Listed in priority order — the first key
@@ -20,7 +20,7 @@
 # 1. LLM provider — pick ONE
 # -----------------------------------------------------------------------------
 #
-# Without a provider key, agentmemory runs in noop mode: observations are
+# Without a provider key, agentcache runs in noop mode: observations are
 # indexed via zero-LLM synthetic compression, hybrid search still works,
 # but LLM-backed summarisation / reflection / consolidation are disabled.
 # The detection order is OPENAI_API_KEY → MINIMAX_API_KEY → ANTHROPIC_API_KEY
@@ -49,12 +49,12 @@
 # (Gemini, OpenRouter, MiniMax, OpenAI LLM, and OpenAI/Cohere/Voyage/OpenRouter
 # embedding). The OpenAI LLM path also honours the OpenAI-scoped
 # OPENAI_TIMEOUT_MS alias for back-compat with v0.9.17 (precedence).
-# AGENTMEMORY_LLM_TIMEOUT_MS=60000                # Default: 60 000 ms (60 s)
+# AGENTCACHE_LLM_TIMEOUT_MS=60000                # Default: 60 000 ms (60 s)
 
 # Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk
 # child sessions). Off by default — the agent-sdk fallback can trigger
 # Stop-hook recursion (#149 follow-up) when invoked from inside Claude Code.
-# AGENTMEMORY_ALLOW_AGENT_SDK=true
+# AGENTCACHE_ALLOW_AGENT_SDK=true
 
 # FALLBACK_PROVIDERS=anthropic,gemini            # Comma-separated chain tried after the primary provider returns an error (e.g. rate limit)
 
@@ -62,7 +62,7 @@
 # 2. Embedding provider — auto-detected, override via EMBEDDING_PROVIDER
 # -----------------------------------------------------------------------------
 #
-# Without an embedding key, agentmemory runs in BM25-only mode for hybrid
+# Without an embedding key, agentcache runs in BM25-only mode for hybrid
 # search. Detection order: EMBEDDING_PROVIDER override → GEMINI_API_KEY →
 # OPENAI_API_KEY → VOYAGE_API_KEY → COHERE_API_KEY → OPENROUTER_API_KEY →
 # local (Xenova/all-MiniLM-L6-v2, 384-dim).
@@ -87,7 +87,7 @@
 # Without a secret, REST endpoints are open on loopback. Set this when
 # you expose the daemon beyond loopback or run behind a reverse proxy.
 
-# AGENTMEMORY_SECRET=your-secret-here
+# AGENTCACHE_SECRET=your-secret-here
 
 # -----------------------------------------------------------------------------
 # 4. Search tuning
@@ -95,7 +95,7 @@
 
 # BM25_WEIGHT=0.4                                # Hybrid search weight for BM25 leg
 # VECTOR_WEIGHT=0.6                              # Hybrid search weight for vector leg
-# AGENTMEMORY_GRAPH_WEIGHT=0.2                   # Graph traversal bonus on smart-search ranking
+# AGENTCACHE_GRAPH_WEIGHT=0.2                   # Graph traversal bonus on smart-search ranking
 # TOKEN_BUDGET=2000                              # Max tokens injected via mem::context per session
 # MAX_OBS_PER_SESSION=500                        # Per-session observation cap before consolidation kicks in
 # SUMMARIZE_CHUNK_SIZE=400                       # When mem::summarize sees a session larger than this, it chunks observations and map-reduces (chunk-summarize → reduce-merge) to stay within the LLM's context window. Default 400 ≈ 50k tokens per chunk at ~110 tok/obs. Native sessions are capped by MAX_OBS_PER_SESSION; chunking primarily matters for bulk-imported jsonl sessions, which bypass that cap.
@@ -105,35 +105,35 @@
 # 5. Behaviour flags
 # -----------------------------------------------------------------------------
 
-# AGENTMEMORY_AUTO_COMPRESS=true                 # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
-# AGENTMEMORY_INJECT_CONTEXT=true                # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
+# AGENTCACHE_AUTO_COMPRESS=true                 # Run LLM compression on every observation batch (requires a provider key). Default off — synthetic compression handles most cases.
+# AGENTCACHE_INJECT_CONTEXT=true                # Inject recalled memories back into agent prompts (#143). Default off — hooks capture observations but do not modify conversation.
 # CONSOLIDATION_ENABLED=true                     # Run the 4-tier consolidation pipeline (memories → semantic → procedural). Default off — opt in once you've measured the LLM cost.
 # CONSOLIDATION_DECAY_DAYS=30                    # Age (days) after which non-reinforced memories decay during consolidation
 # GRAPH_EXTRACTION_ENABLED=true                  # Extract concept-graph edges on remember; powers the graph-traversal recall path
 # GRAPH_EXTRACTION_BATCH_SIZE=8                  # Memories per graph-extraction batch
-# AGENTMEMORY_REFLECT=true                       # Periodically auto-synthesize lessons from memories
-# AGENTMEMORY_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
-# AGENTMEMORY_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
+# AGENTCACHE_REFLECT=true                       # Periodically auto-synthesize lessons from memories
+# AGENTCACHE_DROP_STALE_INDEX=true              # Drop on-disk BM25 / vector index on startup if dim guard fires (#248). Recovery toggle for stuck-state debugging.
+# AGENTCACHE_IMAGE_EMBEDDINGS=true              # Enable image embeddings when an image provider is present (experimental).
 
 # -----------------------------------------------------------------------------
 # 6. CLI / runtime knobs
 # -----------------------------------------------------------------------------
 
-# AGENTMEMORY_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
-# AGENTMEMORY_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
-# AGENTMEMORY_DEBUG=1                            # Trace MCP shim probe + standalone fallback decisions to stderr
-# AGENTMEMORY_FORCE_PROXY=1                      # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)
-# AGENTMEMORY_PROBE_TIMEOUT_MS=2000              # MCP shim livez probe timeout
-# AGENTMEMORY_URL=http://localhost:3111          # REST base URL — honored by status, doctor, MCP shim
-# AGENTMEMORY_VIEWER_URL=http://localhost:3113   # Override the viewer URL printed by `agentmemory status`
-# AGENTMEMORY_EXPORT_ROOT=~/agentmemory-backup   # Default destination for `agentmemory export`
+# AGENTCACHE_TOOLS=all                          # core (7 tools, default) | all (51 tools) — surface exposed to MCP clients
+# AGENTCACHE_SLOTS=memory                       # Comma-separated plugin slot names the CLI should claim
+# AGENTCACHE_DEBUG=1                            # Trace MCP shim probe + standalone fallback decisions to stderr
+# AGENTCACHE_FORCE_PROXY=1                      # Skip the MCP shim livez probe and trust AGENTCACHE_URL (for sandboxed MCP clients that can't reach localhost)
+# AGENTCACHE_PROBE_TIMEOUT_MS=2000              # MCP shim livez probe timeout
+# AGENTCACHE_URL=http://localhost:3111          # REST base URL — honored by status, doctor, MCP shim
+# AGENTCACHE_VIEWER_URL=http://localhost:3113   # Override the viewer URL printed by `agentcache status`
+# AGENTCACHE_EXPORT_ROOT=~/agentcache-backup   # Default destination for `agentcache export`
 
-# STANDALONE_MCP=1                               # MCP shim only — bypass the worker and run @agentmemory/mcp in-process
-# STANDALONE_PERSIST_PATH=~/.agentmemory/local.db  # Path used by the standalone MCP shim's local fallback store
+# STANDALONE_MCP=1                               # MCP shim only — bypass the worker and run @agentcache/mcp in-process
+# STANDALONE_PERSIST_PATH=~/.agentcache/local.db  # Path used by the standalone MCP shim's local fallback store
 
 # Snapshot exporter — periodic snapshots of state_store + stream_store.
 # SNAPSHOT_ENABLED=true
-# SNAPSHOT_DIR=~/.agentmemory/snapshots
+# SNAPSHOT_DIR=~/.agentcache/snapshots
 # SNAPSHOT_INTERVAL=3600                         # Seconds between snapshots
 
 # Team sharing — when set, memories are scoped to (TEAM_ID, USER_ID) tuples.
@@ -153,12 +153,12 @@
 # 8. iii engine pin
 # -----------------------------------------------------------------------------
 #
-# agentmemory currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
-# new sandbox-everything-via-`iii worker add` model that agentmemory
-# hasn't been refactored for yet. Override with AGENTMEMORY_III_VERSION
+# agentcache currently pins iii-engine to v0.11.2 — v0.11.6 introduces a
+# new sandbox-everything-via-`iii worker add` model that agentcache
+# hasn't been refactored for yet. Override with AGENTCACHE_III_VERSION
 # only after migrating to the sandbox model manually.
 
-# AGENTMEMORY_III_VERSION=0.11.2
+# AGENTCACHE_III_VERSION=0.11.2
 
 # -----------------------------------------------------------------------------
 # 9. Claude Code bridge (opt-in)

.kiro/specs/folder-based-memory/design.md

@@ -10,6 +10,45 @@ The redesign eliminates sessions, lessons, slots, actions, crystals, and artefac
 
 ## Architecture
 
+### Implemented Module Layout
+
+```
+src/
+├── app.py              Thin Flask factory — create_app(), WebSocket, CORS
+├── workers.py          Background threads — index rebuild, auto-forget, SIGTERM handler
+├── cli.py              CLI entrypoint (agentmemory serve/migrate/export)
+├── connect.py          Client connection helper
+├── db.py               StateKV — SQLite WAL, per-thread connections, stats()
+├── functions.py        All canonical business logic (large; split planned)
+├── search.py           BM25 + VectorIndex + HybridSearch + 3 embedding providers
+├── viewer_helpers.py   Viewer HTML injection helper
+│
+├── routes/             Flask blueprints (A1 complete)
+│   ├── observations.py   /observe, /agent/observe, /folders, /folder/observations
+│   ├── memories.py       /remember, /agent/remember, /memories, /forget
+│   ├── search.py         /search, /timeline
+│   ├── graph.py          /graph, /graph/stats, /graph/query, /graph/build
+│   ├── health.py         /livez, /health, /audit, /config/flags
+│   ├── mcp.py            /mcp/tools GET+POST (12 active tools)
+│   └── migration.py      /migrate
+│
+├── memory/             Thin shim package re-exporting from functions.py (A2.1)
+│   ├── observe.py        folder_observe, observe, build_synthetic_compression, strip_private_data
+│   ├── remember.py       remember, forget, jaccard_similarity
+│   ├── context.py        context, export_data, rebuild_index
+│   ├── graph.py          folder_graph_build
+│   ├── timeline.py       folder_timeline, folder_search
+│   └── health.py         health_check, auto_forget
+│
+├── storage/            KV scope registry + path utilities (A2.3)
+│   ├── scopes.py         KV class (copy; canonical in functions.py)
+│   ├── paths.py          normalize_folder_path, validate_agent_id, generate_id, fingerprint_id
+│   └── images.py         save_image_to_disk, delete_image, touch_image
+│
+└── viewer/
+    └── index.html      Single-file HTML dashboard (4 tabs: Folders/Memories/Graph/Timeline)
+```
+
 ### High-Level System Diagram
 
 ```mermaid
@@ -20,7 +59,7 @@ graph TD
         A3[Cursor]
     end
 
-    subgraph MCP / REST API ["MCP / REST API (src/app.py)"]
+    subgraph "MCP / REST API (src/routes/)"
         T1[agent_observe]
         T2[memory_recall]
         T3[memory_save / agent_remember]
@@ -28,62 +67,70 @@ graph TD
         T5[memory_export]
         T6[memory_forget]
         T7[memory_diagnose]
+        T8[memory_folders]
+        T9[memory_folder_observations]
+        T10[memory_timeline]
     end
 
-    subgraph Business Logic ["Business Logic (src/functions.py)"]
+    subgraph "Business Logic (src/functions.py)"
         F1[folder_observe]
         F2[folder_search]
         F3[remember / forget]
         F4[folder_timeline]
         F5[folder_graph_build]
-        F6[health_check / export]
+        F6[health_check / export_data]
         F7[strip_private_data]
-        F8[IndexPersistence]
+        F8[IndexPersistence — debounced 5s]
     end
 
-    subgraph Storage ["Storage (src/db.py — SQLite KV)"]
+    subgraph "Storage (src/db.py — SQLite KV)"
         S1["mem:folders  (index)"]
-        S2["mem:folder:{path}:{agent}  (observations + metadata)"]
-        S3[mem:memories]
-        S4["mem:index:bm25:*  (sharded BM25)"]
-        S5[audit_log]
+        S2["mem:folder:{path}:{agent}  (observations)"]
+        S3["mem:foldermeta:{path}:{agent}  (metadata)"]
+        S4[mem:memories]
+        S5["mem:index:bm25:*  (sharded BM25)"]
+        S6["mem:obs_lookup  (O(1) hydration)"]
+        S7[audit_log]
     end
 
-    subgraph Search ["Search (src/search.py)"]
-        SR1[SearchIndex BM25]
-        SR2[VectorIndex cosine]
-        SR3[HybridSearch RRF]
+    subgraph "Search (src/search.py)"
+        SR1[SearchIndex BM25+stemmer+synonyms]
+        SR2[VectorIndex cosine sim]
+        SR3[HybridSearch RRF k=60]
+        EP1[GeminiEmbeddingProvider 768d]
+        EP2[OpenAIEmbeddingProvider 1536d]
+        EP3[SentenceTransformerProvider variable]
     end
 
-    subgraph Viewer ["Viewer (src/viewer/index.html)"]
+    subgraph "Viewer (src/viewer/index.html)"
         V1[Folders tab]
         V2[Memories tab]
         V3[Graph tab]
         V4[Timeline tab]
     end
 
-    A1 & A2 & A3 --> T1 & T2 & T3 & T4 & T5 & T6 & T7
+    A1 & A2 & A3 --> T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 & T9 & T10
     T1 --> F1
     T2 & T4 --> F2
     T3 --> F3
     T5 --> F6
     T6 --> F3
     T7 --> F6
+    T8 & T9 --> S1 & S2
+    T10 --> F4
 
     F1 --> F7
-    F1 --> S2
+    F1 --> S2 & S3 & S1 & S6
     F1 --> SR1 & SR2
-    F1 --> S1
-    F3 --> S3
+    F3 --> S4
     F2 --> SR3
     SR1 & SR2 --> SR3
-    F8 --> S4
+    EP1 & EP2 & EP3 --> SR2
+    F8 --> S5
     SR1 & SR2 --> F8
 
-    F4 --> S2
-    F5 --> S1 & S2 & S3
-
-    S2 & S3 & S4 & S5 --> Storage
+    F4 --> S1 & S2
+    F5 --> S1 & S2 & S4
 
     Viewer --> T2 & T4
     F1 -.->|WebSocket broadcast| Viewer
@@ -150,26 +197,28 @@ sequenceDiagram
 
 ## Components and Interfaces
 
-### Component 1: KV Scope Registry (src/functions.py — `KV` class)
+### Component 1: KV Scope Registry (src/functions.py + src/storage/scopes.py — `KV` class)
 
-**Purpose**: Single source of truth for all KV scope names.
+**Purpose**: Single source of truth for all KV scope names. Defined in `src/functions.py` (canonical) and mirrored to `src/storage/scopes.py` (A2.3).
 
-**New scopes (replaces session-based scopes):**
+**Active scopes:**
 
 ```python
 class KV:
-    # Folder memory index — stores list of all known folder_paths
+    # Folder memory index — key = "{folder_path}:{agent_id}", value = FolderIndexEntry
     folders = "mem:folders"
 
-    # Per-(folder, agent) observations list
-    # key = obs_id, value = observation dict
+    # O(1) observation hydration index — key = obs_id, value = {folderPath, agentId}
+    obs_lookup = "mem:obs_lookup"
+
+    # Per-(folder, agent) observations — key = obs_id, value = FolderObservation
     @staticmethod
     def folder_obs(folder_path: str, agent_id: str) -> str:
         safe_path = folder_path.replace("\\", "/").strip("/")
         safe_agent = agent_id.strip()
         return f"mem:folder:{safe_path}:{safe_agent}"
 
-    # Per-(folder, agent) metadata (last_updated, summary, obs_count)
+    # Per-(folder, agent) metadata — key = "meta", value = FolderMeta
     @staticmethod
     def folder_meta(folder_path: str, agent_id: str) -> str:
         safe_path = folder_path.replace("\\", "/").strip("/")
@@ -179,16 +228,33 @@ class KV:
     # Global long-term memories (unchanged)
     memories = "mem:memories"
 
-    # BM25 index shards (unchanged)
+    # BM25 index shards (sharded, 2MB chunks)
     bm25Index = "mem:index:bm25"
 
-    # Audit scope (unchanged)
+    # Audit log
     audit = "mem:audit"
+
+    # Graph edges (repurposed for folder graph)
+    relations = "mem:relations"
+
+    # Legacy scopes (read-only — for migration only)
+    sessions = "mem:sessions"
+
+    @staticmethod
+    def observations(session_id: str) -> str:
+        return f"mem:obs:{session_id}"
+
+    # Legacy (retained for backward compat code paths)
+    summaries = "mem:summaries"
+    profiles = "mem:profiles"
+    slots = "mem:slots"
+    imageRefs = "mem:image-refs"
+    globalSlots = "mem:global-slots"
 ```
 
-**Scopes removed**: `sessions`, `obs:{session_id}`, `lessons`, `slots`, `slots:global`, `slots:{project}`, `actions`, `action-edges`, `crystals`, `sketches`, `facets`, `sentinels`, `signals`, `checkpoints`, `routines`, `routine-runs`, `profiles`, `summaries`, `semantic`, `procedural`, `commits`, `leases`, `mesh`, `recent-searches`, `claude-bridge`, `insights`, `retention`, `access`, `image-refs`
+**Notable addition**: `obs_lookup = "mem:obs_lookup"` — an O(1) reverse-lookup index that maps `obs_id → {folderPath, agentId}`, enabling fast hydration during search without scanning all folder scopes. Backfilled on startup via `backfill_obs_lookup_if_needed()`.
 
-**Scopes kept**: `memories`, `index:bm25:*`, `audit`, `relations` (repurposed for folder graph edges)
+**Scopes fully removed from active use**: `lessons`, `actions`, `action-edges`, `crystals`, `sketches`, `facets`, `sentinels`, `signals`, `checkpoints`, `routines`, `routine-runs`, `semantic`, `procedural`, `commits`, `leases`, `mesh`, `recent-searches`, `claude-bridge`, `insights`, `retention`, `access`
 
 ---
 
@@ -797,32 +863,62 @@ END
 
 ---
 
-## MCP Tools: Kept, Renamed, and Dropped
+## MCP Tools: Implemented
+
+The server exposes **12 MCP tools** via `GET /agentmemory/mcp/tools` and `POST /agentmemory/mcp/tools`.
 
-### Kept / Repurposed (same tool name, redirected to folder storage)
+### Active Tools
 
-| Tool | New Behavior |
-|------|-------------|
-| `agent_observe` | Required: `folderPath`, `agentId`, `text`. Logs to `(folder_path, agent_id)` scope. `sessionId` accepted but ignored. |
-| `memory_recall` | Searches across all folder observations + global memories via BM25+vector. Optional `folderPath` / `agentId` filters. |
-| `memory_save` | Unchanged — saves to global memories |
-| `agent_remember` | Unchanged — saves to global memories |
-| `memory_smart_search` | Same as `memory_recall` (hybrid search) |
-| `memory_export` | Exports folders + observations + memories in v2 format |
-| `memory_forget` | Accepts `memoryId` (global) OR `folderPath+agentId` (folder observations) |
-| `memory_diagnose` | Returns folder/agent/observation counts instead of session counts |
+| Tool | Description | Notes |
+|------|-------------|-------|
+| `agent_observe` | Log observation to a `(folderPath, agentId)` pair | Required: `folderPath`, `agentId`, `text`. Legacy `sessionId`/`cwd`/`project` accepted as fallback. |
+| `agent_remember` | Save to global long-term memory | Unchanged |
+| `memory_recall` | BM25+vector search across folder obs + global memories | Optional `folderPath`/`agentId` filters |
+| `memory_smart_search` | Alias for `memory_recall` (hybrid search) | Same implementation |
+| `memory_save` | Explicit save to global memory | Unchanged |
+| `memory_export` | Export all data as JSON v2 format | `{folders: [...], memories: [...], version: "2.0"}` |
+| `memory_forget` | Delete memory or folder pair | Accepts `memoryId` OR `folderPath+agentId` |
+| `memory_diagnose` | Health check — folder/agent/obs/memory counts | Replaces session-based counts |
+| `memory_folders` | List all `(folder, agent)` pairs | Returns sorted by `lastUpdated` |
+| `memory_folder_observations` | Get observations for a specific pair | Required: `folderPath`, `agentId` |
+| `memory_timeline` | Folder activity feed | Optional `folderPath`, `agentId`, `limit`, `before`, `after` |
 
-### New Tools
+### Removed Tools (from original session-based model)
 
-| Tool | Description |
-|------|-------------|
-| `memory_folders` | List all (folder, agent) pairs with obsCount and lastUpdated |
-| `memory_folder_observations` | Get observations for a specific `(folderPath, agentId)` pair |
-| `memory_timeline` | Folder activity feed — observations sorted by time, filterable by folderPath/agentId |
+`memory_sessions`, `memory_sessions_list`, `memory_observations` (session-based), `memory_profile`, `memory_lessons`, `memory_lesson_save`, `memory_lesson_recall`, `memory_lesson_search`, `memory_consolidate`, `memory_reflect`, `memory_crystallize`, `memory_slot_list`, `memory_slot_get`, `memory_slot_create`, `memory_slot_append`, `memory_slot_replace`, `memory_slot_delete`, `memory_action_create`, `memory_action_update`, `memory_frontier`, `memory_antigravity_sync`, `memory_antigravity_sync_all`
 
-### Dropped Tools (removed from schema)
+---
 
-`memory_sessions`, `memory_sessions_list`, `memory_observations` (old session-based version), `memory_profile`, `memory_lessons`, `memory_lesson_save`, `memory_lesson_recall`, `memory_lesson_search`, `memory_consolidate`, `memory_reflect`, `memory_crystallize`, `memory_slot_list`, `memory_slot_get`, `memory_slot_create`, `memory_slot_append`, `memory_slot_replace`, `memory_slot_delete`, `memory_action_create`, `memory_action_update`, `memory_frontier`, `memory_antigravity_sync`, `memory_antigravity_sync_all`
+## REST Endpoints: Implemented
+
+### Active Endpoints
+
+| Method | Path | Blueprint | Description |
+|--------|------|-----------|-------------|
+| POST | `/agentmemory/observe` | observations | Legacy compat shim — maps to folder_observe |
+| POST | `/agentmemory/agent/observe` | observations | Folder observation ingest (strict) |
+| GET | `/agentmemory/folders` | observations | List all (folder, agent) pairs |
+| GET | `/agentmemory/folder/observations` | observations | Observations for a pair |
+| POST | `/agentmemory/session/start` | observations | Legacy compat no-op → returns synthetic session ID |
+| POST | `/agentmemory/session/end` | observations | Legacy compat no-op |
+| GET | `/agentmemory/observations` | observations | Legacy compat reads from `mem:obs:{sessionId}` |
+| POST | `/agentmemory/remember` | memories | Save global memory |
+| POST | `/agentmemory/agent/remember` | memories | Save global memory (agent-scoped variant) |
+| GET | `/agentmemory/memories` | memories | List global memories |
+| POST | `/agentmemory/forget` | memories | Delete memory / folder pair |
+| POST | `/agentmemory/search` | search | BM25+vector hybrid search |
+| POST | `/agentmemory/timeline` | search | Folder activity feed |
+| GET | `/agentmemory/graph` | graph | Graph nodes+edges |
+| GET | `/agentmemory/graph/stats` | graph | Node/edge count |
+| POST | `/agentmemory/graph/query` | graph | Reserved (returns empty) |
+| POST | `/agentmemory/graph/build` | graph | Trigger consolidation if enabled |
+| GET | `/agentmemory/livez` | health | Liveness probe (no auth) |
+| GET | `/agentmemory/health` | health | Full health check |
+| GET | `/agentmemory/audit` | health | Audit log |
+| GET | `/agentmemory/config/flags` | health | Feature flags + provider info |
+| GET | `/agentmemory/mcp/tools` | mcp | MCP tool schemas |
+| POST | `/agentmemory/mcp/tools` | mcp | MCP tool dispatch |
+| POST | `/agentmemory/migrate` | migration | Session → folder migration |
 
 ---
 

.kiro/specs/folder-based-memory/tasks.md

@@ -2,15 +2,14 @@
 
 ## Overview
 
-The folder-based memory migration is complete. This plan covers the next phase:
-structural refactoring to eliminate the god-file problem, UX uplift on the viewer
-dashboard, reliability improvements to the storage and indexing layers, and new
-developer-facing features. Work is organized into four parallel tracks that can be
-assigned to different engineers independently.
+The folder-based memory migration is complete. The backend structural refactor (Track A)
+is largely done — blueprints are split, `src/memory/` and `src/storage/` packages exist,
+`db.py` has per-thread connections + WAL checkpoint + stats, and `IndexPersistence` has
+debounce + dirty-flag tracking. This plan tracks what remains.
 
-**Track A — Backend Structure** (Senior Backend)
+**Track A — Backend Structure** ✅ mostly complete
 **Track B — Viewer UX** (Frontend / Full-Stack)
-**Track C — Reliability & Testing** (Backend / QA)
+**Track C — Reliability & Testing** ✅ largely complete
 **Track D — Integrations & DX** (DevEx / Infra)
 
 ---
@@ -19,333 +18,158 @@ assigned to different engineers independently.
 
 ## Track A — Backend Structure Refactor
 
-> Owner: Senior Backend Dev
-> Goal: Break the god files apart so the codebase scales to parallel contributions.
-> Priority: CRITICAL — blocks all other backend work from being clean.
-
 - [x] A1. Split `src/app.py` into Flask blueprints
-  - [x] A1.1 Create `src/routes/` directory with `__init__.py`
-    - Move observation routes (`/observe`, `/agent/observe`, `/folder/observations`, `/folders`) → `src/routes/observations.py`
-    - Move memory routes (`/remember`, `/agent/remember`, `/memories`, `/forget`) → `src/routes/memories.py`
-    - Move search + timeline routes (`/search`, `/timeline`) → `src/routes/search.py`
-    - Move graph routes (`/graph`, `/graph/stats`, `/graph/query`) → `src/routes/graph.py`
-    - Move health + audit routes (`/livez`, `/health`, `/audit`, `/config/flags`) → `src/routes/health.py`
-    - Move MCP routes (`/mcp/tools` GET + POST) → `src/routes/mcp.py`
-    - Move migration route (`/migrate`) → `src/routes/migration.py`
-    - _Each blueprint file registers with `Blueprint(__name__)` and imports only what it needs_
+  - [x] A1.1 Create `src/routes/` directory with blueprints
+    - `src/routes/observations.py` — `/observe`, `/agent/observe`, `/folder/observations`, `/folders`
+    - `src/routes/memories.py` — `/remember`, `/agent/remember`, `/memories`, `/forget`
+    - `src/routes/search.py` — `/search`, `/timeline`
+    - `src/routes/graph.py` — `/graph`, `/graph/stats`, `/graph/query`, `/graph/build`
+    - `src/routes/health.py` — `/livez`, `/health`, `/audit`, `/config/flags`
+    - `src/routes/mcp.py` — `/mcp/tools` GET + POST
+    - `src/routes/migration.py` — `/migrate`
 
   - [x] A1.2 Rebuild `src/app.py` as a thin factory
-    - `create_app()` factory function: init DB, init embeddings, register all blueprints, set up WebSocket, register `after_request` CORS hook
-    - Keep `init_app()` logic but move background thread setup into a separate `src/workers.py`
-    - `if __name__ == "__main__"` block stays minimal — just `create_app().run()`
-    - Target: `app.py` under 150 lines after refactor
+    - `create_app()` factory: init DB, init embeddings (D5.3 priority: Gemini → OpenAI → SentenceTransformer → BM25-only), register all blueprints, set up WebSocket, register CORS hook
+    - Background worker setup moved to `src/workers.py`
+    - `app.py` is now ~170 lines
 
   - [x] A1.3 Validate no route regressions after blueprint split
-    - Run full `pytest tests/` suite; manually hit every endpoint via `/livez` sanity pass
-    - Check WebSocket still connects and broadcasts after split
-
-- [ ] A2. Split `src/functions.py` into focused modules
-  - [ ] A2.1 Create `src/memory/` package
-    - `src/memory/observe.py` — `folder_observe()`, `observe()`, `build_synthetic_compression()`, `strip_private_data()`
-    - `src/memory/remember.py` — `remember()`, `forget()`, `jaccard_similarity()`
-    - `src/memory/context.py` — `context()`, `export_data()`, `rebuild_index()`
-    - `src/memory/graph.py` — `folder_graph_build()`, `get_relations()`, `add_relation()`, `folderColor()`
-    - `src/memory/timeline.py` — `folder_timeline()`, `folder_search()`
-    - `src/memory/health.py` — `health_check()`, `auto_forget()`
+    - `tests/test_route_regressions.py` covers all main endpoints
+
+- [x] A2. Split `src/functions.py` into focused modules
+  - [x] A2.1 Create `src/memory/` package
+    - `src/memory/observe.py` — thin re-export shim for `folder_observe`, `observe`, `build_synthetic_compression`, `strip_private_data`
+    - `src/memory/remember.py` — thin re-export shim for `remember`, `forget`, `jaccard_similarity`
+    - `src/memory/context.py` — thin re-export shim for `context`, `export_data`, `rebuild_index`
+    - `src/memory/graph.py` — thin re-export shim for `folder_graph_build`
+    - `src/memory/timeline.py` — thin re-export shim for `folder_timeline`, `folder_search`
+    - `src/memory/health.py` — thin re-export shim for `health_check`, `auto_forget`
+    - _Note: the shims currently delegate back to `functions.py`. The canonical implementation still lives in `functions.py`._
 
   - [~] A2.2 Keep `src/functions.py` as a compatibility shim
-    - Re-export everything from `src/memory/*` via `from memory.observe import *` etc.
-    - This avoids breaking `app.py` imports during the transition period
-    - Remove the shim in a follow-up PR once blueprints are fully referencing the new modules
+    - All routes import from `functions` directly; `src/memory/*` shims exist for future decoupling
 
-  - [~] A2.3 Move `KV` class and path utilities to `src/storage/`
-    - `src/storage/scopes.py` — `KV` class with all scope definitions
+  - [x] A2.3 Move `KV` class and path utilities to `src/storage/`
+    - `src/storage/scopes.py` — `KV` class (copy; canonical version still in `functions.py`)
     - `src/storage/paths.py` — `normalize_folder_path()`, `validate_agent_id()`, `generate_id()`, `fingerprint_id()`
     - `src/storage/images.py` — `save_image_to_disk()`, `delete_image()`, `touch_image()`, `is_managed_image_path()`
 
-- [ ] A3. Fix `src/db.py` connection management
-  - [~] A3.1 Implement per-thread persistent connections using `threading.local()`
-    - Replace every `conn = self._get_conn()` / `conn.close()` pattern with a `_local = threading.local()` cache
-    - Connection is opened once per thread and reused; close only on explicit `teardown()` or thread exit
-    - Keep the write `_lock` for serializing INSERT/UPDATE/DELETE operations
-
-  - [~] A3.2 Add WAL checkpoint on graceful shutdown
-    - Register a `SIGTERM` / `atexit` handler in `src/workers.py` that calls `PRAGMA wal_checkpoint(FULL)` before exit
-    - This ensures the BM25/vector index shards are flushed to the DB before the process dies
-
-  - [~] A3.3 Add `db.stats()` method for the health endpoint
-    - Return `{"db_size_bytes": ..., "kv_row_count": ..., "audit_row_count": ..., "wal_size_bytes": ...}`
-    - Used by the upgraded `/health` endpoint
-
-- [ ] A4. Debounce index persistence writes
-  - [~] A4.1 Replace `IndexPersistence.schedule_save()` with a real debounce queue
-    - Use a `threading.Timer` that resets on each call; fires the actual `save()` after 5 seconds of inactivity
-    - This prevents a save on every single observation write under high throughput
+- [x] A3. Fix `src/db.py` connection management
+  - [x] A3.1 Per-thread persistent connections via `threading.local()`
+  - [x] A3.2 WAL checkpoint on graceful shutdown (`atexit` + `SIGTERM`/`SIGINT` handlers in `workers.py`)
+  - [x] A3.3 `db.stats()` method returning `db_size_bytes`, `kv_row_count`, `audit_row_count`, `wal_size_bytes`
 
-  - [~] A4.2 Add dirty-flag tracking to `SearchIndex` and `VectorIndex`
-    - Set `self._dirty = True` in `add()` and `remove()`; reset in `save()`
-    - Skip `save()` entirely if `not _dirty`
-
-  - [~] A4.3 Write unit test for debounce behavior
-    - Assert that 100 rapid `add()` calls result in exactly 1 persistence save, not 100
+- [x] A4. Debounce index persistence writes
+  - [x] A4.1 `IndexPersistence.schedule_save()` uses `threading.Timer` (5s debounce)
+  - [x] A4.2 `_dirty` flag on `SearchIndex` and `VectorIndex` — skip save if not dirty
+  - [~] A4.3 Unit test for debounce behavior → `tests/test_debounce.py` exists
 
 ---
 
 ## Track B — Viewer UX Overhaul
 
 > Owner: Frontend / Full-Stack Dev
-> Goal: Elevate the viewer from a debug tool to a real developer dashboard.
-> Priority: HIGH — highest user-visible impact.
 
 - [ ] B1. Add Command Palette (`Ctrl+K` / `Cmd+K`)
-  - [~] B1.1 Build command palette overlay in `index.html`
-    - Fuzzy-search across: folder names, memory content snippets, observation titles, tab names
-    - Data sources: in-memory cache of last-loaded folders + memories (no extra API calls on keypress)
-    - Keyboard: `↑`/`↓` to navigate results, `Enter` to navigate to item, `Escape` to close
-    - Show result type badge (Folder / Memory / Observation) and secondary detail (agentId / timestamp)
-
-  - [~] B1.2 Register global keydown listener
-    - `document.addEventListener("keydown", ...)` — detect `Ctrl+K` on Windows/Linux, `Cmd+K` on Mac
-    - Focus input field on open; re-focus last active element on close
-
-  - [~] B1.3 Style command palette
-    - Modal overlay with `backdrop-filter: blur(4px)` behind the panel
-    - Max-width 640px, centered; input at top, results list below with keyboard-highlight state
-    - Respect `data-theme="dark"` CSS vars; animate open/close with `transform: translateY(-8px) → 0` + `opacity`
+  - [~] B1.1–B1.3 Not yet implemented in `src/viewer/index.html`
 
 - [ ] B2. Replace Canvas graph with D3 force-directed SVG
-  - [~] B2.1 Add D3 v7 via CDN with CSP nonce
-    - Load `d3.v7.min.js` via `<script nonce="__AGENTMEMORY_VIEWER_NONCE__">` inline or from self-hosted path
-    - Remove the existing Canvas `<canvas>` element and hand-rolled physics loop
-
-  - [~] B2.2 Implement D3 force simulation on SVG
-    - Nodes as `<circle>` + `<text>` SVG groups; size proportional to `obsCount`
-    - Three link types rendered as distinct path styles: `same-parent` (dashed `stroke-dasharray: 6,3`), `cross-ref` (solid), `agent-shared` (dotted `stroke-dasharray: 2,4`)
-    - `d3.forceManyBody().strength()` tuned per node count: `-80` for < 20 nodes, `-200` for 20–100, `-400` for 100+
-
-  - [~] B2.3 Add zoom/pan and click-to-expand
-    - `d3.zoom()` for pan + scroll-to-zoom; double-click node to highlight its edges and neighbors, dim all others
-    - Click on a node opens the Folders tab filtered to that `folderPath`
-
-  - [~] B2.4 Fix graph edge label overlap bug (ROADMAP item)
-    - Use `d3.forceCollide()` on label bounding boxes; set `textAnchor` dynamically based on node position relative to center
-    - Labels only show at zoom > 0.6; below that, show labels only for hovered node
+  - [~] B2.1–B2.4 Not yet implemented
 
 - [ ] B3. Implement virtual scroll on Timeline and Folders tabs
-  - [~] B3.1 Build a reusable `VirtualList` helper in JS
-    - Takes `container`, `items[]`, `rowHeight`, `renderItem(item) → HTMLElement`
-    - Uses `IntersectionObserver` on a sentinel element at the bottom to load next page
-    - Maintains a window of ~50 rendered DOM nodes, recycling off-screen rows
-
-  - [~] B3.2 Apply `VirtualList` to Timeline tab
-    - Replace current `observations.forEach(renderObsCard)` with `VirtualList`
-    - Fetch first 50 observations; load next 50 on scroll near bottom via `/timeline` with `before` cursor from last item's timestamp
-
-  - [~] B3.3 Apply `VirtualList` to Folders tab observation drill-down
-    - When a folder row is expanded, load observations with the same virtual scroll pattern
+  - [~] B3.1–B3.3 Not yet implemented
 
 - [ ] B4. First-run onboarding experience
-  - [~] B4.1 Detect empty state on Dashboard tab load
-    - Check `health_check` response: if `observationCount === 0` and `memoryCount === 0`, show onboarding card
-
-  - [~] B4.2 Build onboarding card component
-    - Three-step guide: (1) Configure `AGENTMEMORY_SECRET` env var, (2) Set `GEMINI_API_KEY` for semantic search, (3) Point your agent hook at `POST /agentmemory/agent/observe`
-    - Each step shows a code snippet (pre-formatted, with a copy button) and a green checkmark if the feature is already active (read from `/config/flags` response)
-    - Dismissable with "Got it" button; stores dismissed state in `localStorage`
-
-  - [~] B4.3 Add "copy to clipboard" utility function
-    - `copyToClipboard(text)` uses `navigator.clipboard.writeText()` with fallback to `document.execCommand("copy")`
-    - Show a transient "Copied!" tooltip for 1.5 seconds after click
+  - [~] B4.1–B4.3 Not yet implemented
 
 - [ ] B5. Add MCP Tool Tester tab
-  - [~] B5.1 Add "Tools" tab to the tab bar
-    - Fetch `GET /agentmemory/mcp/tools` on tab activate; render a list of all tools with name + description
-
-  - [~] B5.2 Build tool invocation panel
-    - Click a tool → show its `inputSchema` as an auto-generated JSON editor (textarea pre-filled with `{}` containing all required keys)
-    - "Run" button posts to `POST /agentmemory/mcp/tools` with `{name, arguments}`
-    - Response rendered as syntax-highlighted JSON below the editor; error state shown in red
-
-  - [~] B5.3 Add request/response history for the session
-    - Keep last 10 tool calls in memory; render as collapsible history entries above the editor
-    - Each history entry shows tool name, timestamp, and success/error badge
+  - [~] B5.1–B5.3 Not yet implemented
 
 - [ ] B6. Viewer polish and accessibility
-  - [~] B6.1 Fix dark mode inconsistencies
-    - Audit all components against `data-theme="dark"` CSS vars; find and fix the graph tooltip and graph controls that don't fully respond to theme changes
-    - Test in both themes: all text must meet WCAG AA contrast ratio (4.5:1 for body, 3:1 for large text)
-
-  - [~] B6.2 Add keyboard navigation for tabs
-    - `Tab` key cycles through tab buttons; `Enter`/`Space` activates; `←`/`→` arrow keys move between tabs when a tab has focus
-    - Add `role="tablist"`, `role="tab"`, `aria-selected`, `aria-controls` ARIA attributes to the tab bar
-
-  - [~] B6.3 Add loading skeleton states
-    - Replace `<div class="loading">Loading...</div>` with animated skeleton placeholder cards that match the shape of the real content
-    - Use CSS `@keyframes shimmer` with a `background: linear-gradient(90deg, ...)` animation
+  - [~] B6.1–B6.3 Not yet implemented
 
 ---
 
 ## Track C — Reliability & Testing
 
-> Owner: Backend / QA Dev
-> Goal: Close the test coverage gap and harden the system against bad inputs and restarts.
-> Priority: HIGH — required before any production deployment.
-
-- [ ] C1. Write tests for the core observe/remember/search/context pipeline
-  - [~] C1.1 Create `tests/test_observe_core.py`
-    - Test `observe()` with valid payload → returns obs dict with correct fields
-    - Test `observe()` with missing `sessionId` / `hookType` / `timestamp` → raises `ValueError`
-    - Test that `strip_private_data()` fires and `[REDACTED_SECRET]` appears in stored obs
-    - Test that `MAX_OBS_PER_SESSION` env cap raises `ValueError` when exceeded
-
-  - [~] C1.2 Create `tests/test_remember.py`
-    - Test `remember()` creates a new memory with `isLatest=True`
-    - Test that a second `remember()` with > 0.7 Jaccard similarity sets `isLatest=False` on the old memory and links via `parentId`
-    - Test that a second `remember()` with < 0.7 similarity creates an independent second memory
-
-  - [~] C1.3 Create `tests/test_search.py`
-    - Test `SearchIndex.add()` + `SearchIndex.search()` returns the added document at rank 1 for an exact-match query
-    - Test prefix matching: index `"authentication"`, search `"authen"` → doc appears in results
-    - Test synonym expansion: index `"database connection"`, search `"db conn"` → doc appears via synonym map
-    - Test `HybridSearch.search()` in BM25-only mode (no embedding provider) returns same results as `SearchIndex.search()`
-
-  - [~] C1.4 Create `tests/test_context.py`
-    - Test `context()` respects `TOKEN_BUDGET` — returned context string is under budget
-    - Test that pinned slot content appears first in context output
-    - Test that empty DB returns a well-formed but minimal context dict
-
-- [ ] C2. Write Hypothesis property tests
-  - [~] C2.1 Create `tests/test_properties.py` with all 8 property tests
-    - **Property 1: Pair Isolation** — two distinct `(folderPath, agentId)` pairs never share observations
-    - **Property 2: Observation Count Consistency** — `meta.obsCount == len(kv.list(folder_obs_scope))`
-    - **Property 3: Index Coverage** — every written pair has a `KV.folders` entry
-    - **Property 4: Privacy Invariant** — no stored obs text matches any secret regex pattern after `folder_observe()`
-    - **Property 5: Timeline Ordering** — `folder_timeline()` always returns results sorted newest-first
-    - **Property 6: Forget Completeness** — after `forget({folderPath, agentId})`, all three scopes are empty and BM25 has no entry for any obs from that pair
-    - **Property 7: Memory Version Uniqueness** — only one memory per concept cluster has `isLatest=True`
-    - **Property 8: Path Normalization Idempotency** — `normalize(normalize(p)) == normalize(p)` for all valid inputs
-    - Use `tmp_path` pytest fixture for isolated SQLite DB per test; `@settings(max_examples=50)`
-
-- [ ] C3. Add integration tests for REST endpoints
-  - [~] C3.1 Create `tests/test_api.py` using Flask test client
-    - Test `POST /agentmemory/agent/observe` → 201 with obs id
-    - Test `POST /agentmemory/agent/observe` missing `folderPath` → 400
-    - Test `POST /agentmemory/search` with query → 200 with results list
-    - Test `GET /agentmemory/folders` → 200 with folders list
-    - Test `GET /agentmemory/health` → 200 with `folderCount`, `observationCount` keys
-    - Test `GET /agentmemory/livez` → 200 without auth (open endpoint)
-    - Test authenticated endpoints return 401 when `AGENTMEMORY_SECRET` is set but token is wrong
-
-- [ ] C4. Improve HuggingFace sync reliability
+> All test files exist and are passing.
+
+- [x] C1. Core pipeline tests
+  - [x] `tests/test_observe_core.py` — folder observe validation, privacy stripping, cap enforcement
+  - [x] `tests/test_remember.py` — memory creation, Jaccard dedup, independent memories
+  - [x] `tests/test_search.py` — BM25 add/search, prefix matching, synonym expansion, hybrid search
+  - [x] `tests/test_context.py` — TOKEN_BUDGET, context compilation
+
+- [x] C2. Hypothesis property tests
+  - [x] `tests/test_properties.py` — 8 properties:
+    1. Pair Isolation
+    2. Observation Count Consistency
+    3. Index Coverage
+    4. Privacy Invariant
+    5. Timeline Ordering
+    6. Forget Completeness
+    7. Memory Version Uniqueness
+    8. Path Normalization Idempotency
+
+- [x] C3. Integration tests
+  - [x] `tests/test_api.py` — Flask test client hitting all main endpoints
+  - [x] `tests/test_route_regressions.py` — regression suite after blueprint split
+
+- [x] Additional test files
+  - [x] `tests/test_folder_observe.py` — folder_observe unit tests
+  - [x] `tests/test_folder_graph_build.py` — graph builder tests
+  - [x] `tests/test_forget.py` — forget function tests
+  - [x] `tests/test_normalize.py` — path normalization tests
+  - [x] `tests/test_obs_lookup.py` — obs_lookup index tests
+  - [x] `tests/test_migration.py` — session → folder migration tests
+  - [x] `tests/test_timeline.py` — folder_timeline tests
+  - [x] `tests/test_graph.py` — graph edge tests
+  - [x] `tests/test_debounce.py` — IndexPersistence debounce test
+
+- [ ] C4. HuggingFace sync reliability
   - [~] C4.1 Replace mtime-based sync trigger with audit log high-water mark
-    - On each sync iteration, read `MAX(ts)` from `audit_log`; compare to last-synced high-water mark stored in a local `.sync_state` file
-    - Only upload if `current_max_ts > last_synced_ts`; update the watermark after successful upload
-    - This eliminates false-positive uploads caused by WAL mode mtime changes
+  - [~] C4.2 Add sync status to `/health` endpoint
 
-  - [~] C4.2 Add sync status to the `/health` endpoint
-    - Report `last_sync_at` (ISO timestamp of last successful HF upload), `sync_status` (`"ok"` / `"never"` / `"error"`), and `db_size_bytes`
-    - Read from `.sync_state` file; if file doesn't exist, report `"never"`
-
-- [ ] C5. Add graceful shutdown handler
-  - [~] C5.1 Register `SIGTERM` and `SIGINT` handlers in `src/workers.py`
-    - On signal: set a global `_shutting_down` flag; wait for any in-flight `schedule_save()` debounce timer to fire; call `persistence.save()` synchronously; log shutdown message
-    - Exit cleanly with code 0
+- [x] C5. Graceful shutdown handler
+  - [x] `src/workers.py` registers SIGTERM/SIGINT handlers, flushes persistence, runs WAL checkpoint
 
 ---
 
 ## Track D — Integrations & Developer Experience
 
-> Owner: DevEx / Infra Dev
-> Goal: Make agentmemory easier to install, configure, and connect to agents.
-> Priority: MEDIUM — high value but not blocking.
-
 - [ ] D1. Clean up dead code and scratch files
-  - [~] D1.1 Delete scratch and personal utility files
-    - Remove `scratch_diff.txt`, `scratch_test_import.py` from repo root
-    - Remove `push_local_data.py` and `push_second_brain.py` — these are personal sync scripts, not library code
-    - Remove `migrate_dolt_to_sqlite.py` — the migration is done; archive it in `docs/migration/` if it needs to be kept for reference
+  - [~] D1.1 Remove scratch files (scratch_diff.txt, push_local_data.py, push_second_brain.py, migrate_dolt_to_sqlite.py)
+  - [~] D1.2 Remove 410-stub route handlers from app.py
+  - [~] D1.3 Fix dead references in `mcp_stdio.py`
+  - [~] D1.4 Move/rename `DESIGN.md` → `docs/viewer-design-system.md`; ensure `ARCHITECTURE.md` is accurate
 
-  - [~] D1.2 Remove all 410-stub route handlers from `app.py`
-    - Delete route functions for: `api_session_start`, `api_session_end`, `api_session_commit`, `api_session_by_commit`, `api_sessions`, `api_replay_sessions`, `api_antigravity_sync`, `api_lessons_list`, `api_lessons_save`, `api_lessons_search`, `api_lessons_strengthen`, `api_slots_list`, `api_slots_get`, `api_slots_create`, `api_slots_append`, `api_slots_replace`, `api_slots_delete`, `api_slots_reflect`, `api_timeline_legacy`
-    - These return 410 and serve no purpose except confusion; the routes are already documented as removed
+- [ ] D2. Fix CORS and security hardening
+  - [x] D2.1 CORS configurable via `AGENTMEMORY_CORS_ORIGINS` env var (implemented in `app.py`)
+  - [~] D2.2 Stop injecting `AGENTMEMORY_SECRET` into HTML template (viewer token via cookie)
 
-  - [~] D1.3 Fix dead references in `mcp_stdio.py`
-    - `perform_antigravity_sync_all_local()` calls `/summarize` and `/slot/reflect` which are 410 — update or remove these calls
-    - The Antigravity sync logic (both functions) is personal/business-specific; move to `examples/antigravity_sync.py` and remove from the generic MCP bridge
-    - Clean up the double-import of `os`, `json`, `requests` inside `perform_antigravity_sync_local()`
+- [ ] D3. Prebuilt agent hook scripts
+  - [~] D3.1–D3.4 `hooks/` directory may contain scripts; need verification and docs update
 
-  - [~] D1.4 Move `DESIGN.md` and clarify its purpose
-    - Rename to `docs/viewer-design-system.md` — the current name `DESIGN.md` implies system architecture
-    - Create a real `ARCHITECTURE.md` at the repo root that documents the Flask blueprint structure, module responsibilities, KV scope layout, and data flow (observe → BM25/vector → WebSocket → viewer)
+- [x] D4. `pip`-installable package
+  - [x] `pyproject.toml` with `agentmemory` entry point → `src.cli:main`
+  - [x] `src/cli.py` CLI entrypoint exists
+  - [~] D4.3 GitHub Actions CI workflow updates
 
-- [ ] D2. Fix CORS and security hardening
-  - [~] D2.1 Move CORS allowlist to configuration
-    - Replace the `after_request` string-matching logic with a configurable `AGENTMEMORY_CORS_ORIGINS` env var (comma-separated)
-    - Default to `http://localhost:*,http://127.0.0.1:*,vscode-webview://*` — still localhost-only but driven by config
-    - Add `chrome-extension://` support as an explicit opt-in via env var, not hardcoded
-
-  - [~] D2.2 Stop injecting `AGENTMEMORY_SECRET` into HTML template
-    - The current `__AGENTMEMORY_AUTO_TOKEN__` replacement embeds the raw secret in the page source
-    - Replace with a session-scoped viewer token: on page load, the server issues a short-lived viewer token (signed HMAC of `secret + timestamp`, valid 1h) via a `Set-Cookie` header
-    - The viewer uses this cookie for API calls; the actual `AGENTMEMORY_SECRET` never touches the DOM
-
-- [ ] D3. Build prebuilt agent hook scripts
-  - [~] D3.1 Create `hooks/claude-code-hook.sh` for Claude Code
-    - Bash script that posts to `POST /agentmemory/agent/observe` on each tool use
-    - Reads `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` from environment
-    - Include `folderPath` from `$PWD`, `agentId` from `$CLAUDE_AGENT_ID` or `"claude-code"`
-
-  - [~] D3.2 Create `hooks/cursor-hook.js` for Cursor
-    - JavaScript snippet for Cursor's `.cursorrules` hook system
-    - Same endpoint and payload structure as the bash version
-
-  - [~] D3.3 Create `hooks/powershell-hook.ps1` for terminal sessions
-    - Formalize and generalize the hook currently documented in `agentmemory.md`
-    - Parameterize `$ServerUrl` and `$AgentId`; ship as a ready-to-source snippet
-
-  - [~] D3.4 Update `INSTALL_FOR_AGENTS.md` with hook setup instructions
-    - One section per agent type; link to the corresponding hook script in `hooks/`
-    - Include the `.env` file format and `AGENTMEMORY_SECRET` setup steps
-
-- [ ] D4. Build `pip`-installable package
-  - [~] D4.1 Add `pyproject.toml`
-    - Package name: `agentmemory`; entry point: `agentmemory = src.app:main`
-    - Include `src/viewer/` as package data
-    - Python `>=3.10` requirement
-
-  - [~] D4.2 Add CLI entrypoint
-    - `agentmemory serve [--port PORT] [--host HOST]` — starts the Flask server
-    - `agentmemory migrate` — runs `migrate_sessions_to_folders()` and prints summary
-    - `agentmemory export [--output FILE]` — runs `export_data()` and writes JSON
-
-  - [~] D4.3 Update GitHub Actions CI workflow
-    - Add steps: `pip install -e .[dev]`, `pytest tests/ -v`, `pip install build; python -m build`
-    - Run on `push` to `main` and `pull_request`
-
-- [ ] D5. Additional embedding provider support
-  - [~] D5.1 Add `OpenAIEmbeddingProvider` class to `src/search.py`
-    - Mirror the `GeminiEmbeddingProvider` interface: `embed(text)`, `embed_batch(texts)`, `dimensions` (1536 for `text-embedding-3-small`)
-    - Use `urllib.request` (no new dependencies); read API key from `OPENAI_API_KEY` env var
-
-  - [~] D5.2 Add local `sentence-transformers` provider (optional install)
-    - `SentenceTransformerProvider` class; lazy-import `sentence_transformers`; log a clear error if not installed
-    - Default model: `all-MiniLM-L6-v2` (384 dims); configurable via `AGENTMEMORY_LOCAL_EMBEDDING_MODEL` env var
-
-  - [~] D5.3 Auto-select embedding provider in `init_app()`
-    - Priority: `GEMINI_API_KEY` → `OPENAI_API_KEY` → `AGENTMEMORY_LOCAL_EMBEDDING_MODEL` → BM25-only
-    - Log which provider was selected on startup
+- [x] D5. Additional embedding providers
+  - [x] `OpenAIEmbeddingProvider` in `src/search.py` (D5.1)
+  - [x] `SentenceTransformerProvider` in `src/search.py` (D5.2)
+  - [x] Auto-select provider in `create_app()` — Gemini → OpenAI → SentenceTransformer → BM25-only (D5.3)
 
 ---
 
-## Notes
+## Remaining High-Priority Work
 
-- **Track A must be completed before any other backend feature work.** The blueprint split is the prerequisite that makes parallel development safe. Do not add new routes to the monolithic `app.py`.
-- **Track B and Track C can run in parallel** with Track A. The viewer and test suite touch different files.
-- **Track D tasks D1.1–D1.3 (cleanup) can be done immediately** — they are deletions and do not require Track A to finish first.
-- All new routes follow the existing auth pattern: call `check_auth()` at the top; never skip it.
-- All new viewer JS follows the existing CSP constraint: no inline event handlers, all scripts nonce-tagged.
-- Property tests in `tests/test_properties.py` (C2.1) are the authoritative source; unit tests in C1 are complementary, not replacements.
-- The `D2.2` security fix (token injection) should be shipped before any public/shared deployment.
+The following items are not yet done and represent the bulk of remaining effort:
+
+1. **Track B (Viewer UX)** — Command palette, D3 graph, virtual scroll, onboarding, MCP tool tester, accessibility polish
+2. **D1.2** — Remove 410 stub routes from `app.py` (they live in `observations.py` as compat shims — keep those, but the dead `app.py` stubs should be gone; already done since the monolith was split)
+3. **D2.2** — Viewer token security (secret not in DOM)
+4. **C4** — HF sync reliability with audit watermark
 
 ---
 
@@ -356,33 +180,28 @@ assigned to different engineers independently.
   "waves": [
     {
       "id": 0,
-      "label": "Cleanup (no dependencies)",
-      "tasks": ["D1.1", "D1.2", "D1.3", "D1.4"]
+      "label": "Completed — structural foundation",
+      "tasks": ["A1.1", "A1.2", "A1.3", "A2.1", "A2.3", "A3.1", "A3.2", "A3.3", "A4.1", "A4.2", "C1.1", "C1.2", "C1.3", "C1.4", "C2.1", "C3.1", "C5.1", "D4.1", "D4.2", "D5.1", "D5.2", "D5.3", "D2.1"]
     },
     {
       "id": 1,
-      "label": "Structural foundation",
-      "tasks": ["A1.1", "A2.3", "A3.1", "C1.1", "C1.2", "C1.3", "B4.1", "B4.2"]
+      "label": "Next — viewer UX foundation",
+      "tasks": ["B4.1", "B4.2", "B4.3", "B1.1", "B2.1", "B3.1"]
     },
     {
       "id": 2,
-      "label": "Module split + UX foundation",
-      "tasks": ["A1.2", "A2.1", "A2.2", "A3.2", "A4.1", "B1.1", "B2.1", "B3.1", "C1.4", "D2.1"]
+      "label": "Viewer components",
+      "tasks": ["B1.2", "B1.3", "B2.2", "B3.2", "B3.3", "B5.1", "B5.2", "D2.2"]
     },
     {
       "id": 3,
-      "label": "Blueprint validation + UX components",
-      "tasks": ["A1.3", "A3.3", "A4.2", "A4.3", "B1.2", "B1.3", "B2.2", "B3.2", "B3.3", "C2.1", "C3.1", "D2.2"]
+      "label": "Advanced viewer + sync",
+      "tasks": ["B2.3", "B2.4", "B5.3", "B6.1", "B6.2", "B6.3", "C4.1", "C4.2"]
     },
     {
       "id": 4,
-      "label": "Advanced features",
-      "tasks": ["B2.3", "B2.4", "B4.3", "B5.1", "B5.2", "C4.1", "C4.2", "C5.1", "D3.1", "D3.2", "D3.3", "D5.1"]
-    },
-    {
-      "id": 5,
       "label": "Polish + packaging",
-      "tasks": ["B5.3", "B6.1", "B6.2", "B6.3", "D3.4", "D4.1", "D4.2", "D4.3", "D5.2", "D5.3"]
+      "tasks": ["D1.1", "D1.2", "D1.3", "D1.4", "D3.1", "D3.2", "D3.3", "D3.4", "D4.3"]
     }
   ]
 }

.windsurfrules

@@ -1,20 +1,23 @@
-# Agent Memory Rules
+# Agent Cache Rules
 
-This workspace is integrated with long-term semantic memory via `agentmemory-python`.
-You must act as your own memory manager by calling the memory MCP tools at critical boundaries.
+This workspace is integrated with long-term semantic memory via `agentcache-python`.
+You must act as your own memory manager by calling the cache MCP tools at critical boundaries.
 
 ## Rules & Workflow
 
 1. **Initial Search (Prefetch Context)**:
-   At the start of every session or new task, immediately call `memory_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
-   - Example: `memory_smart_search(query="jwt token rotation logic")`
+   At the start of every session or new task, immediately call `cache_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, and past work.
+   - Example: `cache_smart_search(query="jwt token rotation logic")`
 
-2. **Lessons & Insights Capture**:
+2. **Log Observations**:
+   As you work, call `agent_observe` to record what you are doing. Include `folderPath` (the working directory), `agentId` (your agent name), and `text` (what happened).
+   - Example: `agent_observe(folderPath="/your/project/path", agentId="windsurf", text="Refactored auth middleware to use JWT rotation")`
+
+3. **Save Long-Term Memories**:
    When you successfully debug a complex error, discover an undocumented requirement, or establish a convention, persist it:
-   - Call `memory_lesson_save` to record lessons that improve your coding capabilities. Duplicate saves strengthen confidence scores.
-   - Call `memory_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
+   - Call `cache_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
 
-3. **Checklist Before Ending**:
+4. **Checklist Before Ending**:
    Before stating a task is complete:
-   - Reflect on whether any lessons learned should be saved.
-   - Call `memory_reflect` to automatically distribute observations into slots if needed.
+   - Reflect on whether any insights should be saved via `cache_save`.
+   - Review the folder activity feed with `cache_timeline` to confirm all significant work was captured.

AGENTS.md

@@ -1,23 +1,53 @@
-# agentmemory-python — Agent Instructions
+# agentcache-python — Agent Instructions
 
 ## What this project is
 
-A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no iii-engine, no Dolt. Agents use it to store observations, memories, lessons, and slots, and to retrieve context at session start.
+A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no iii-engine, no Dolt. Agents use it to store observations scoped to `(folder_path, agent_id)` pairs and global long-term memories. The viewer, MCP tools, and REST API are built around the **folder-based memory model** — sessions, lessons, slots, and actions are removed.
 
 ## Project layout
 
 ```
 src/
-├── app.py          Flask server — all endpoints, WebSocket broadcaster
-├── db.py           SQLite StateKV — WAL mode, audit_log table
-├── functions.py    Core business logic (observe, remember, search, context)
-├── search.py       BM25 index + Gemini vector index + HybridSearch (RRF)
+├── app.py              Thin Flask factory — create_app(), WebSocket, CORS hook
+├── cli.py              CLI entrypoint (agentcache serve/migrate/export)
+├── connect.py          Client connection helper
+├── db.py               StateKV — SQLite WAL, per-thread connections, stats()
+├── functions.py        All canonical business logic (large; memory/ shims delegate here)
+├── search.py           BM25 + VectorIndex + HybridSearch + 3 embedding providers
+├── viewer_helpers.py   Viewer HTML injection helper
+├── workers.py          Background threads — index rebuild, auto-forget, SIGTERM handler
+│
+├── routes/             Flask blueprints
+│   ├── observations.py   /observe, /agent/observe, /folders, /folder/observations
+│   ├── memories.py       /remember, /agent/remember, /memories, /forget
+│   ├── search.py         /search, /timeline
+│   ├── graph.py          /graph, /graph/stats, /graph/query, /graph/build
+│   ├── health.py         /livez, /health, /audit, /config/flags
+│   ├── mcp.py            /mcp/tools GET+POST (12 active tools)
+│   └── migration.py      /migrate
+│
+├── memory/             Thin shim package — delegates to functions.py
+│   ├── observe.py        folder_observe, observe, build_synthetic_compression, strip_private_data
+│   ├── remember.py       remember, forget, jaccard_similarity
+│   ├── context.py        context, export_data, rebuild_index
+│   ├── graph.py          folder_graph_build
+│   ├── timeline.py       folder_timeline, folder_search
+│   └── health.py         health_check, auto_forget
+│
+├── storage/            KV scope registry + path/ID utilities
+│   ├── scopes.py         KV class (mirrored from functions.py)
+│   ├── paths.py          normalize_folder_path, validate_agent_id, generate_id, fingerprint_id
+│   └── images.py         save_image_to_disk, delete_image, touch_image
+│
 └── viewer/
-    └── index.html  Single-file HTML dashboard
+    └── index.html      Single-file HTML dashboard (4 tabs: Folders / Memories / Graph / Timeline)
+
 sync.py             HuggingFace dataset backup/restore
 Dockerfile          HF Space container definition
 start.sh            Boot: restore DB → start server → start sync loop
 requirements.txt    flask, flask-sock, requests, websockets, python-dateutil, huggingface_hub
+pyproject.toml      pip-installable package (agentcache==0.9.8, Python ≥3.10)
+tests/              pytest suite — unit, integration, and Hypothesis property tests
 ```
 
 ## Running
@@ -29,130 +59,130 @@ python src/app.py
 # Viewer at http://localhost:3111/viewer
 ```
 
-No build step. No external database. SQLite file lives at `~/.agentmemory/agentmemory.db`.
+No build step. No external database. SQLite file lives at `~/.agentcache/agentcache.db`.
 
 ## Architecture
 
+### Data Model — Folder-Based Memory
+
+The primary unit of storage is `(folder_path, agent_id)`. Each agent accumulates observations scoped to the folder it is working in. Global long-term memories remain unchanged.
+
 ### Storage — `src/db.py`
 
-`StateKV` wraps a single SQLite file with two tables:
+`StateKV` wraps a single SQLite file with:
+- `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — all data as JSON
+- `audit_log(id, ts, agent_id, message)` — write audit trail
+- `sync_state_metadata(key, value)` — HuggingFace sync watermark
 
-- `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — all data as JSON, namespaced by scope
-- `audit_log(id, ts, agent_id, message)` — write audit trail (replaces Dolt versioning)
+Per-thread persistent connections via `threading.local()`. WAL checkpoint registered via `atexit` and on `SIGTERM`/`SIGINT`.
 
-Key scopes (defined in `functions.py` `KV` class):
+Key scopes (defined in `functions.py` `KV` class and mirrored in `src/storage/scopes.py`):
 
 | Scope | Content |
 |-------|---------|
-| `mem:sessions` | Session objects |
-| `mem:obs:{session_id}` | Observations for a session |
-| `mem:memories` | Long-term memories |
-| `mem:lessons` | Lessons with confidence scores |
-| `mem:slots` | Pinned memory slots |
+| `mem:folders` | Index of all `(folder_path, agent_id)` pairs — key = `"{path}:{agent}"` |
+| `mem:folder:{path}:{agent}` | Observations for a pair — key = obs_id |
+| `mem:foldermeta:{path}:{agent}` | Metadata for a pair (obsCount, lastUpdated, summary) |
+| `mem:obs_lookup` | O(1) reverse-lookup: obs_id → `{folderPath, agentId}` |
+| `mem:memories` | Global long-term memories |
+| `mem:index:bm25:*` | Sharded BM25 index (2MB chunks) |
+| `mem:audit` | Audit log entries |
 | `mem:relations` | Knowledge graph edges |
-| `mem:actions` | Work items / actions |
+| `mem:sessions` | Legacy session store (read-only, migration only) |
+| `mem:obs:{session_id}` | Legacy per-session observations (read-only, migration only) |
 
 ### Business logic — `src/functions.py`
 
-Global state:
-- `_bm25_index` / `_vector_index` — in-memory search indexes, rebuilt from DB on startup if empty
-- `_hybrid_search` — combines BM25 + vector; only initialized when Gemini key is set
-- `_stream_broadcaster` — WebSocket broadcast callback injected by `app.py`
+All canonical implementations live here. `src/memory/*` are thin shims that re-export from this module (for future decoupling).
 
 **Observation pipeline:**
 ```
-raw payload → strip_private_data() → build_synthetic_compression()
-→ stored in kv_store → BM25-indexed → vector-indexed (if key set)
-→ audit_log entry → WebSocket broadcast
+raw payload → normalize_folder_path() → validate_agent_id() → strip_private_data()
+→ build obs dict → kv.set(folder_obs scope) → upsert folder_meta + folders index
+→ kv.set(obs_lookup) → BM25-indexed → vector-indexed (if key set)
+→ schedule_save() (debounced 5s) → audit log → WebSocket broadcast
 ```
 
 **Memory versioning:** `remember()` checks Jaccard similarity against existing memories. If > 0.7 match found, new memory supersedes old (`isLatest=False` on old, `parentId` set on new).
 
-**Context compilation** (`context()`): assembles pinned slots → project profile → lessons (scored by confidence × project match) → past session summaries, capped at `TOKEN_BUDGET` tokens (estimated at `len/3`).
+**Search:** `folder_search()` uses `HybridSearch` (BM25 + vector, RRF k=60). Falls back to BM25-only when no embedding provider is configured. Results include both folder observations and global memories.
 
-**Lessons:** fingerprinted by SHA-256 of content. Duplicate saves strengthen confidence (`+0.1 × (1 - conf)`). Weekly decay reduces confidence by `decayRate × weeks`; soft-deleted at ≤ 0.1 confidence with 0 reinforcements.
+**`health_check()`** returns: `folderCount`, `agentCount`, `pairCount`, `observationCount`, `memoryCount`, `bm25IndexSize`, `vectorIndexSize`, `dbPath`, plus `db.stats()` fields.
 
 ### Search — `src/search.py`
 
-- `SearchIndex`: BM25 with custom Porter stemmer. Persisted to `kv_store` in sharded 2MB chunks via `IndexPersistence`.
-- `VectorIndex`: cosine similarity over Gemini 768-dim embeddings stored as base64-encoded float32 arrays.
-- `HybridSearch`: fuses BM25 + vector scores with RRF (k=60, reciprocal rank fusion).
+- `SearchIndex`: BM25 with Porter stemmer and synonym expansion. Dirty-flag (`_dirty`) prevents unnecessary saves. Persisted in sharded 2MB KV chunks.
+- `VectorIndex`: cosine similarity over embeddings stored as base64-encoded float32 arrays. Also has `_dirty` flag.
+- `HybridSearch`: fuses BM25 + vector scores with RRF (k=60).
 
-### Server — `src/app.py`
+**Embedding providers** (auto-selected by priority in `create_app()`):
 
-Boot order:
-1. Initialize `StateKV` (SQLite)
-2. Initialize embedding provider (Gemini if key set)
-3. Initialize `IndexPersistence`
-4. Rebuild BM25/vector index if empty (background thread)
-5. Start Flask on `III_REST_PORT` (default 3111)
+| Priority | Provider | Env var | Dimensions |
+|----------|----------|---------|------------|
+| 1 | `GeminiEmbeddingProvider` | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | 768 |
+| 2 | `OpenAIEmbeddingProvider` | `OPENAI_API_KEY` | 1536 |
+| 3 | `SentenceTransformerProvider` | `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | variable |
+| 4 | BM25-only | — | — |
 
-Auth: all endpoints check `AGENTMEMORY_SECRET` via timing-safe `hmac.compare_digest` Bearer token comparison if the env var is set. `/livez` is always open.
+### Server — `src/app.py`
 
-WebSocket at `/stream/mem-live/viewer` broadcasts raw + compressed observations to connected viewers.
+Boot order:
+1. Load `~/.agentcache/.env` if present
+2. Initialize `StateKV` (SQLite)
+3. Auto-select embedding provider (Gemini → OpenAI → SentenceTransformer → BM25-only)
+4. Initialize `IndexPersistence` (load or rebuild)
+5. Backfill `obs_lookup` index if missing
+6. Create Flask app, register blueprints
+7. Set up WebSocket `/stream/mem-live/viewer`
+8. Register CORS `after_request` hook
+9. Start background workers (index rebuild if empty/stale, auto-forget loop)
+
+Auth: all endpoints check `AGENTCACHE_SECRET` via `hmac.compare_digest`. `/livez` is always open.
 
 ## MCP Tools
 
-The server exposes 31 MCP tools via `GET /agentmemory/mcp/tools` (schema) and `POST /agentmemory/mcp/tools` (execution).
+The server exposes **12 MCP tools** via `GET /agentcache/mcp/tools` and `POST /agentcache/mcp/tools`.
 
 | Tool | Description | Status |
 |------|-------------|--------|
-| `memory_recall` | Search past session observations | Working |
-| `memory_save` | Save long-term memory (concepts/files as string or array) | Working |
-| `memory_sessions` | List recent sessions | Working |
-| `memory_sessions_list` | Retrieve all memory sessions | Working |
-| `memory_smart_search` | Hybrid semantic+keyword search | Working |
-| `memory_timeline` | Chronological observations | Working |
-| `memory_observations` | Get observations for session | Working |
-| `memory_profile` | User/project profile | Working |
-| `memory_lessons` | List saved lessons | Working |
-| `memory_lesson_save` | Save lesson from session | Working |
-| `memory_lesson_recall` | Search lessons by query | Working |
-| `memory_lesson_search` | Search lessons (keywords) | Working |
-| `memory_consolidate` | Summarize sessions, extract memory | Working |
-| `memory_reflect` | Reflect on session, update context | Working |
-| `memory_diagnose` | Health check subsystems | Working |
-| `memory_forget` | Delete memory/session/observations | Working |
-| `memory_export` | Export all data as JSON | Working |
-| `agent_observe` | Log agent execution observation | Working |
-| `agent_remember` | Save agent memory to long-term | Working |
-| `memory_antigravity_sync` | Sync Antigravity transcripts | Working |
-| `memory_antigravity_sync_all` | Master sync: transcript + crystallize + reflect | Working |
-| `memory_slot_list` | List all pinned memory slots | Working |
-| `memory_slot_get` | Retrieve a specific pinned slot | Working |
-| `memory_slot_create` | Create/overwrite pinned slot | Working |
-| `memory_slot_append` | Append text content to slot | Working |
-| `memory_slot_replace` | Replace slot content | Working |
-| `memory_slot_delete` | Delete pinned memory slot | Working |
-| `memory_action_create` | Create a new work item / action | Working |
-| `memory_action_update` | Update fields of existing action | Working |
-| `memory_frontier` | Get active/pending actions | Working |
-| `memory_crystallize` | Summarize session observations | Working |
-
-**MCP stdio wrapper:** `src/mcp_stdio.py` reads `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` from environment variables dynamically.
+| `agent_observe` | Log observation to a `(folderPath, agentId)` pair | Working |
+| `agent_remember` | Save to global long-term memory | Working |
+| `memory_recall` | Search folder obs + global memories (BM25+vector) | Working |
+| `memory_smart_search` | Hybrid semantic+keyword search (alias for recall) | Working |
+| `memory_save` | Explicitly save insight to long-term memory | Working |
+| `memory_export` | Export all data as JSON (v2 format) | Working |
+| `memory_forget` | Delete memory or folder pair observations | Working |
+| `memory_diagnose` | Health check (folder/agent/obs/memory counts) | Working |
+| `memory_folders` | List all `(folder, agent)` pairs | Working |
+| `memory_folder_observations` | Get observations for a specific pair | Working |
+| `memory_timeline` | Folder activity feed (sorted by time, filterable) | Working |
+
+**MCP stdio wrapper:** `src/mcp_stdio.py` reads `AGENTCACHE_URL` and `AGENTCACHE_SECRET` from environment variables dynamically.
 
 ## Consistency rules
 
 **When adding a REST endpoint:**
-1. Add the route in `src/app.py`
-2. Update `API Reference` section in `README.md`
-3. Add the MCP tool in `src/app.py` MCP dispatch if it should be agent-callable
+1. Add the route in the appropriate `src/routes/*.py` blueprint
+2. Update the `API Reference` section in `README.md`
+3. Add the MCP tool in `src/routes/mcp.py` if it should be agent-callable
 
 **When adding an MCP tool:**
-1. Add the schema to the `GET /mcp/tools` response in `src/app.py`
-2. Add the handler case to the `POST /mcp/tools` dispatch in `src/app.py`
+1. Add the schema to the `GET /mcp/tools` response in `src/routes/mcp.py`
+2. Add the handler case to the `POST /mcp/tools` dispatch in `src/routes/mcp.py`
 3. Update the tool table in `README.md`
 4. Update `AGENTS.md` tool list
 
 **When changing data scopes:**
-1. Update the `KV` class in `src/functions.py`
-2. Update the scope table in this file
+1. Update the `KV` class in `src/functions.py` (canonical)
+2. Mirror the change in `src/storage/scopes.py`
+3. Update the scope table in this file
 
 ## Code patterns
 
 ### Adding a new KV scope
 
 ```python
+# In src/functions.py KV class (canonical):
 class KV:
     your_scope = "mem:your-scope"
 
@@ -164,21 +194,21 @@ class KV:
 ### Adding a REST endpoint
 
 ```python
-@app.route('/agentmemory/your-path', methods=['POST'])
+# In the appropriate src/routes/*.py blueprint:
+@your_bp.route('/agentcache/your-path', methods=['POST'])
 def your_endpoint():
-    if AGENTMEMORY_SECRET:
-        auth = request.headers.get('Authorization', '')
-        if not hmac.compare_digest(auth, f'Bearer {AGENTMEMORY_SECRET}'):
-            return jsonify({'error': 'Unauthorized'}), 401
-    body = request.get_json(silent=True) or {}
+    auth_err = _check_auth()
+    if auth_err:
+        return auth_err
+    body = request.get_json(force=True) or {}
     # validate fields explicitly — never pass raw body to functions
-    result = your_function(kv, body.get('field'))
+    result = functions.your_function(_get_kv(), body.get('field'))
     return jsonify(result), 200
 ```
 
 ### Adding an MCP tool schema
 
-In the `GET /mcp/tools` handler, add to the tools list:
+In `src/routes/mcp.py`, `GET /agentcache/mcp/tools` handler:
 ```python
 {
     "name": "memory_your_tool",
@@ -193,11 +223,11 @@ In the `GET /mcp/tools` handler, add to the tools list:
 }
 ```
 
-In the `POST /mcp/tools` handler, add a case:
+In `src/routes/mcp.py`, `POST /agentcache/mcp/tools` handler:
 ```python
 elif tool_name == 'memory_your_tool':
     query = args.get('query', '')
-    result = your_function(kv, query)
+    result = functions.your_function(kv, query)
     return jsonify({'content': [{'type': 'text', 'text': json.dumps(result)}]})
 ```
 
@@ -206,26 +236,44 @@ elif tool_name == 'memory_your_tool':
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `III_REST_PORT` / `PORT` | `3111` | Server port |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables vector search + Gemini LLM |
-| `AGENTMEMORY_SECRET` | — | Bearer token auth |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables Gemini vector search (priority 1) |
+| `OPENAI_API_KEY` | — | Enables OpenAI vector search (priority 2) |
+| `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | — | SentenceTransformer model name (priority 3) |
+| `AGENTCACHE_SECRET` | — | Bearer token auth |
 | `AGENT_ID` | — | Default agent ID |
-| `AGENTMEMORY_AGENT_SCOPE=isolated` | — | Filter data to current agent |
-| `MAX_OBS_PER_SESSION` | `500` | Observations hard cap |
+| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filter data to current agent |
+| `AGENTCACHE_CWD` | — | Fallback folder path for legacy clients |
+| `MAX_OBS_PER_FOLDER` | `2000` | Observations hard cap per (folder, agent) pair |
 | `TOKEN_BUDGET` | `2000` | Context compilation cap |
 | `GRAPH_EXTRACTION_ENABLED` | `false` | Graph extraction (needs LLM) |
 | `CONSOLIDATION_ENABLED` | `false` | Consolidation (needs LLM) |
-| `AGENTMEMORY_AUTO_COMPRESS` | `false` | LLM compression |
+| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM compression |
+| `AUTO_FORGET_ENABLED` | — | Auto-forget sweep (set to "false" to disable) |
+| `AGENTCACHE_CORS_ORIGINS` | see app.py | Comma-separated allowed origins |
+| `AGENTCACHE_IMAGE_STORE_MAX_BYTES` | 500MB | Image store byte limit |
 | `HF_TOKEN` | — | HuggingFace sync |
-| `AGENTMEMORY_DATASET_REPO` | — | HF dataset repo for backup |
+| `AGENTCACHE_DATASET_REPO` | — | HF dataset repo for backup |
 
-## HuggingFace Space deployment
+## Testing
 
-Data flow: `agentmemory.db` (SQLite) ↔ `sync.py` ↔ HF dataset repo.
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+Tests live in `tests/` — 17 test files covering unit tests, integration tests (Flask test client), and Hypothesis property tests.
+
+Key test files:
+- `tests/test_properties.py` — 8 correctness properties (pair isolation, obs count consistency, index coverage, privacy, timeline ordering, forget completeness, memory version uniqueness, path normalization idempotency)
+- `tests/test_api.py` — Flask test client integration tests
+- `tests/test_route_regressions.py` — regression suite after blueprint split
 
-`sync.py` uses mtime fingerprinting (`_quick_hash`) to detect changes before uploading. Backup only runs when the DB actually changed. Restore uses `hf_hub_download` for targeted file fetches rather than full `snapshot_download`.
+## HuggingFace Space deployment
+
+Data flow: `agentcache.db` (SQLite) ↔ `sync.py` ↔ HF dataset repo.
 
 `start.sh` sequence:
-1. Restore `agentmemory.db` from dataset repo
+1. Restore `agentcache.db` from dataset repo
 2. Start `python src/app.py` in background
 3. Run `sync.py` in a loop (backup every ~60s if changed)
 
@@ -233,10 +281,9 @@ Data flow: `agentmemory.db` (SQLite) ↔ `sync.py` ↔ HF dataset repo.
 
 Single-file HTML dashboard, served directly by Flask at `/viewer`. No build step, no bundler.
 
-Tabs: Dashboard, Sessions, Memories, Graph, Timeline, Lessons, Slots, Replay.
-
-**Graph tab** (`loadGraph()`): fetches sessions + memories, groups by `project` path into folder nodes. Edges connect folders that share concepts or parent path segments. Each folder node gets a unique color via `folderColor(id)` — a hash-to-hex function that converts the folder path string into a distinct HSL color. The simulation uses force-directed physics with per-node-count repulsion tuning.
-
-## No tests yet
+Tabs: **Folders**, **Memories**, **Graph**, **Timeline**.
 
-No test runner is configured. When adding tests, use `pytest` — it's the standard Python choice and requires no extra config for basic test discovery (`test_*.py` files).
+- **Folders tab**: lists all `(folder, agent)` pairs; click a row to drill into observations
+- **Memories tab**: global long-term memories with search
+- **Graph tab**: force-directed graph — nodes = folder paths, edges = same-parent / cross-ref / agent-shared
+- **Timeline tab**: all observations sorted by timestamp desc, filterable by folder path and agent ID

ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# agentmemory-python — Architecture
+# agentcache-python — Architecture
 
 ## Overview
 
@@ -44,8 +44,8 @@ src/
 ├── viewer_helpers.py   make_viewer_response() — reads viewer/index.html,
 │                       injects nonce + version, sets CSP headers.
 │
-├── mcp_stdio.py        stdio MCP bridge: reads AGENTMEMORY_URL and
-│                       AGENTMEMORY_SECRET, proxies tool calls to the HTTP API.
+├── mcp_stdio.py        stdio MCP bridge: reads AGENTCACHE_URL and
+│                       AGENTCACHE_SECRET, proxies tool calls to the HTTP API.
 │
 └── viewer/
     └── index.html      Single-file HTML dashboard (no bundler).
@@ -55,7 +55,7 @@ src/
 
 ## KV Scope Layout
 
-All data lives in a single SQLite file (`~/.agentmemory/agentmemory.db`) in two tables:
+All data lives in a single SQLite file (`~/.agentcache/agentcache.db`) in two tables:
 
 - `kv_store(scope TEXT, key TEXT, value TEXT, PRIMARY KEY(scope, key))` — JSON values
 - `audit_log(id, ts, agent_id, message)` — write audit trail
@@ -120,7 +120,7 @@ If found, old memory is marked `isLatest=False` and new memory sets `parentId`.
 
 ## Authentication
 
-All endpoints except `/livez` check `AGENTMEMORY_SECRET` via timing-safe
+All endpoints except `/livez` check `AGENTCACHE_SECRET` via timing-safe
 `hmac.compare_digest` Bearer token comparison. No secret → no auth check.
 
 ---
@@ -138,7 +138,7 @@ Priority order (auto-selected at startup):
 
 1. `GeminiEmbeddingProvider` — if `GEMINI_API_KEY` or `GOOGLE_API_KEY` is set (768 dims)
 2. `OpenAIEmbeddingProvider` — if `OPENAI_API_KEY` is set (1536 dims)
-3. `SentenceTransformerProvider` — if `AGENTMEMORY_LOCAL_EMBEDDING_MODEL` is set
+3. `SentenceTransformerProvider` — if `AGENTCACHE_LOCAL_EMBEDDING_MODEL` is set
 4. BM25-only fallback
 
 Without an embedding provider, `HybridSearch` falls back to pure BM25.

CLAUDE.md

@@ -4,100 +4,106 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Is
 
-Python reimplementation of the agentmemory persistent memory server. Exposes a REST API + WebSocket stream + MCP tools endpoint that AI coding agents use to store and retrieve session observations, long-term memories, lessons, and pinned memory slots. Backed by a Dolt SQL Server (MySQL-compatible).
+A Python REST + WebSocket + MCP memory server backed by SQLite. No Node.js, no Dolt. Agents use it to store observations scoped to `(folder_path, agent_id)` pairs and global long-term memories. The architecture is **folder-based** — sessions, lessons, slots, and actions are removed.
 
 ## Running
 
-**Prerequisite**: Dolt SQL Server must be running on `127.0.0.1:3306` with a database named `agentmemory`. Config is read from `~/.agentmemory/.env` at startup.
-
 ```bash
-# Start the memory API server and built-in viewer (port 3111)
+pip install -r requirements.txt
 python src/app.py
+# Server on http://localhost:3111
+# Viewer at http://localhost:3111/viewer
 ```
 
-The built-in HTML dashboard is accessible at:
-- `http://localhost:3111/viewer` or `http://localhost:3111/`
+No build step. SQLite file lives at `~/.agentcache/agentcache.db`. Config optionally loaded from `~/.agentcache/.env`.
 
-No build step. No test runner is configured yet.
+## Running Tests
 
-## Key Environment Variables
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
 
-Set in `~/.agentmemory/.env` or as system env vars:
+## Key Environment Variables
 
 | Variable | Default | Purpose |
 |---|---|---|
 | `III_REST_PORT` / `PORT` | `3111` | API server port |
-| `DOLT_HOST/PORT/USER/PASSWORD/DATABASE` | `127.0.0.1/3306/root//"agentmemory"` | Dolt connection |
-| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search; without it, BM25-only |
-| `AGENTMEMORY_SECRET` | — | Enables Bearer token auth on all endpoints |
-| `AGENT_ID` | — | Default agent ID for scope isolation |
-| `AGENTMEMORY_AGENT_SCOPE=isolated` | — | Filters sessions/obs to current `AGENT_ID` |
-| `DOLT_AUTO_COMMIT=false` | auto-commit | Disable Dolt versioning commits per write |
-| `MAX_OBS_PER_SESSION` | `500` | Hard cap on observations per session |
-| `TOKEN_BUDGET` | `2000` | Max tokens in compiled context response |
-| `GRAPH_EXTRACTION_ENABLED=true` | `false` | Knowledge graph extraction (requires LLM) — **disabled by default** |
-| `CONSOLIDATION_ENABLED=true` | `false` | Memory consolidation (requires LLM) — **disabled by default** |
-| `AGENTMEMORY_AUTO_COMPRESS=true` | `false` | LLM-powered observation compression |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Gemini vector search (priority 1) |
+| `OPENAI_API_KEY` | — | OpenAI vector search (priority 2) |
+| `AGENTCACHE_LOCAL_EMBEDDING_MODEL` | — | SentenceTransformer model (priority 3) |
+| `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
+| `AGENT_ID` | — | Default agent ID |
+| `AGENTCACHE_AGENT_SCOPE=isolated` | — | Filter data to current `AGENT_ID` |
+| `AGENTCACHE_CWD` | — | Fallback folder path for legacy clients |
+| `MAX_OBS_PER_FOLDER` | `2000` | Hard cap on observations per (folder, agent) pair |
+| `TOKEN_BUDGET` | `2000` | Context compilation cap |
+| `GRAPH_EXTRACTION_ENABLED` | `false` | Knowledge graph extraction (needs LLM) |
+| `CONSOLIDATION_ENABLED` | `false` | Memory consolidation (needs LLM) |
+| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM-powered observation compression |
+| `AGENTCACHE_CORS_ORIGINS` | see app.py | Comma-separated allowed CORS origins |
 
 ## Architecture
 
 ### `src/db.py` — Storage Layer
-`StateKV` wraps a single Dolt table `kv_store(scope VARCHAR, key VARCHAR, value LONGTEXT)`. All data is JSON-serialized. Scopes are namespaced strings (e.g. `mem:sessions`, `mem:obs:{session_id}`). Dolt versioning is triggered via `CALL dolt_add('-A')` + `CALL dolt_commit(...)` stored procedures — this is what makes the store git-versioned.
 
-### `src/functions.py` — Business Logic
-All core operations live here. Important globals:
-- `_bm25_index` / `_vector_index` — in-memory search indexes (rebuilt from DB on startup if empty)
-- `_hybrid_search` — combines BM25 + vector search; only initialized when embedding provider is set
-- `_stream_broadcaster` — WebSocket broadcast callback injected by `app.py`
+`StateKV` wraps SQLite with two tables:
+- `kv_store(scope, key, value)` — all data as JSON, namespaced by scope
+- `audit_log(id, ts, agent_id, message)` — write audit trail
 
-Key scopes are defined in the `KV` class. Dynamic scopes: `KV.observations(session_id)` → `mem:obs:{session_id}`.
+Per-thread persistent connections via `threading.local()`. WAL checkpoint on shutdown.
 
-**Observation pipeline**: raw payload → `strip_private_data()` → `build_synthetic_compression()` → stored + BM25-indexed + vector-indexed + Dolt-committed + WebSocket-broadcast.
+Key scopes: `mem:folders` (index), `mem:folder:{path}:{agent}` (observations), `mem:foldermeta:{path}:{agent}` (metadata), `mem:obs_lookup` (O(1) reverse lookup), `mem:memories` (global), `mem:index:bm25:*` (search).
 
-**Memory versioning**: `remember()` checks Jaccard similarity against existing memories; if > 0.7 match found, the new memory supersedes the old one (`isLatest=False` on old, `parentId` set on new).
+### `src/functions.py` — Business Logic
 
-**Context compilation** (`context()`): assembles pinned slots → project profile → lessons (scored by confidence × project match) → past session summaries, capped at `TOKEN_BUDGET` tokens (estimated at `len/3`).
+All core implementations. Key functions:
+- `folder_observe(kv, payload)` — ingest a folder-scoped observation
+- `folder_search(kv, query, limit, folder_path, agent_id)` — BM25+vector hybrid search
+- `folder_timeline(kv, limit, folder_path, agent_id, before, after)` — activity feed
+- `folder_graph_build(kv)` — build graph nodes + edges
+- `remember(kv, data)` / `forget(kv, data)` — global memory management
+- `health_check(kv)` — system stats
+- `export_data(kv, data)` — v2 JSON export
+- `migrate_sessions_to_folders(kv, dry_run)` — legacy migration
 
-**Lessons**: fingerprinted by SHA-256 of content. Duplicate saves strengthen confidence (`+0.1 × (1 - conf)`). Weekly decay sweep reduces confidence by `decayRate × weeks`; soft-deleted at ≤ 0.1 confidence with 0 reinforcements.
+`src/memory/*` contains thin shim modules that re-export from here.
 
 ### `src/search.py` — Search Indexes
-- `SearchIndex`: BM25 with custom Porter stemmer. Persisted to Dolt in sharded 2MB chunks via `IndexPersistence`.
-- `VectorIndex`: cosine similarity over Gemini 768-dim embeddings stored as base64-encoded float32 arrays.
-- `HybridSearch`: fuses BM25 + vector scores with RRF (reciprocal rank fusion).
-
-### `src/app.py` — Flask API
-Initializes DB → embedding provider → index persistence → rebuilds index if empty (background thread). All endpoints check `AGENTMEMORY_SECRET` via timing-safe Bearer token comparison. WebSocket at `/stream/mem-live/viewer` broadcasts raw + compressed observations to connected viewers.
-
-MCP tools are served at `GET /agentmemory/mcp/tools` (schema list) and `POST /agentmemory/mcp/tools` (tool call dispatch).
-
-### `src/viewer/index.html` — Built-in HTML Dashboard
-Interactive web dashboard served directly by the Flask server. Provides real-time view of active sessions, timelines, memories with search, slots editor, and DB migration panel. Connects to the Flask backend via REST and live WebSockets. Imports legacy TypeScript `.bin` files via `src/import_data.py`.
-
-## API Surface
-
-Base path: `/agentmemory/`
-
-- `GET /livez` — health/liveness (no auth)
-- `POST /observe` — ingest a hook event observation
-- `POST /agent/observe` — simplified observe for direct agent use
-- `POST /remember` / `POST /agent/remember` — save long-term memory
-- `POST /forget` — delete memory/session/observations
-- `POST /context` — compile context for a session+project
-- `POST /search` — hybrid BM25+vector search
-- `POST/GET /lessons` — lessons CRUD + `/lessons/search`, `/lessons/strengthen`
-- `GET/POST /slots`, `GET/POST/DELETE /slot` — memory slots CRUD
-- `POST /slot/reflect` — auto-populate slots from session observations
-- `POST/GET /session/start|end|commit` — session lifecycle
-- `GET /sessions`, `GET /observations` — list data
-- `GET/POST /relations` — knowledge graph edges
-- `POST /evolve` — create new memory version
-- `POST /timeline` — chronological observation window
-- `GET /profile` — project profile (top concepts/files); no `?project` → returns list of all known projects
-- `GET /actions` — list actions (`?limit`, `?status`)
-- `POST /actions` — create action
-- `PATCH /actions/<id>` — update action status/fields
-- `GET /frontier` — pending+active actions sorted by priority
-- `GET /insights` — list insights (`?limit`)
-- `GET /replay/sessions` — sessions list for replay tab
-- `GET /replay/load?sessionId=<id>` — full session + observations for replay
-- `GET/POST /mcp/tools` — MCP protocol adapter
+
+- `SearchIndex`: BM25 with Porter stemmer + synonym expansion. `_dirty` flag prevents unnecessary saves.
+- `VectorIndex`: cosine similarity over embeddings as base64 float32. `_dirty` flag.
+- `HybridSearch`: RRF fusion (k=60) of BM25 + vector.
+- `GeminiEmbeddingProvider`, `OpenAIEmbeddingProvider`, `SentenceTransformerProvider`.
+
+### `src/app.py` — Flask Factory
+
+`create_app()`: init DB → auto-select embedding provider → init IndexPersistence → backfill obs_lookup → register blueprints → setup WebSocket → register CORS → start background workers.
+
+### `src/routes/` — Flask Blueprints
+
+| Blueprint | Endpoints |
+|-----------|-----------|
+| `observations.py` | `/observe`, `/agent/observe`, `/folders`, `/folder/observations`, legacy session shims |
+| `memories.py` | `/remember`, `/agent/remember`, `/memories`, `/forget` |
+| `search.py` | `/search`, `/timeline` |
+| `graph.py` | `/graph`, `/graph/stats`, `/graph/query`, `/graph/build` |
+| `health.py` | `/livez`, `/health`, `/audit`, `/config/flags` |
+| `mcp.py` | `/mcp/tools` GET+POST (12 tools) |
+| `migration.py` | `/migrate` |
+
+### `src/workers.py` — Background Threads
+
+- Index rebuild thread (if BM25 index is empty or out of sync on boot)
+- Auto-forget sweep loop (hourly)
+- SIGTERM/SIGINT handlers: flush `IndexPersistence`, WAL checkpoint, exit 0
+
+### `src/viewer/index.html` — Dashboard
+
+Single-file HTML, served at `/viewer`. Tabs: **Folders**, **Memories**, **Graph**, **Timeline**. No build step.
+
+## MCP Tools (12 active)
+
+`agent_observe`, `agent_remember`, `memory_recall`, `memory_smart_search`, `memory_save`, `memory_export`, `memory_forget`, `memory_diagnose`, `memory_folders`, `memory_folder_observations`, `memory_timeline`
+
+Full schema at `GET /agentcache/mcp/tools`.

Caddyfile

@@ -4,16 +4,16 @@
     handle /stream/* {
         reverse_proxy localhost:3112 {
             header_up Host localhost:3112
-            header_up Authorization "Bearer {env.AGENTMEMORY_SECRET}"
+            header_up Authorization "Bearer {env.AGENTCACHE_SECRET}"
         }
     }
 
     # Route REST API endpoints (iii-http on 3111)
     # Caddy injects the secret so the dashboard viewer works without exposing it to the browser
-    handle /agentmemory/* {
+    handle /agentcache/* /agentmemory/* {
         reverse_proxy localhost:3111 {
             header_up Host localhost:3111
-            header_up Authorization "Bearer {env.AGENTMEMORY_SECRET}"
+            header_up Authorization "Bearer {env.AGENTCACHE_SECRET}"
         }
     }
 

INSTALL_FOR_AGENTS.md

@@ -1,10 +1,10 @@
-# Install agentmemory-python (agent runbook)
+# Install agentcache-python (agent runbook)
 
-You are a coding agent. Follow this runbook top to bottom to install agentmemory-python, wire it into yourself, and verify that persistent memory works. Run each command, check the result against the "Expect" note, then move on.
+You are a coding agent. Follow this runbook top to bottom to install agentcache-python, wire it into yourself, and verify that persistent memory works. Run each command, check the result against the "Expect" note, then move on.
 
 ## What you are installing
 
-agentmemory-python is a local memory server for coding agents. It runs on your machine, exposes a REST API on port 3111 and an MCP endpoint, and stores all memories in a single SQLite file at `~/.agentmemory/agentmemory.db`. It is built with Python and Flask — no Node.js, no external database, no daemon to manage separately.
+agentcache-python is a local memory server for coding agents. It runs on your machine, exposes a REST API on port 3111 and an MCP endpoint, and stores all memories in a single SQLite file at `~/.agentcache/agentcache.db`. It is built with Python and Flask — no Node.js, no external database, no daemon to manage separately.
 
 Default mode works with no API key. It runs BM25 keyword search out of the box. Set `GEMINI_API_KEY` to also enable vector semantic search.
 
@@ -12,13 +12,13 @@ Default mode works with no API key. It runs BM25 keyword search out of the box.
 
 - Python 3.10 or newer. Check with `python --version` or `python3 --version`.
 - pip. Check with `pip --version`.
-- Port 3111 free. If taken, set `III_REST_PORT=<other>` in `~/.agentmemory/.env`.
+- Port 3111 free. If taken, set `III_REST_PORT=<other>` in `~/.agentcache/.env`.
 
 ## 1. Clone the repo
 
 ```bash
-git clone https://github.com/Yash030/agentmemory-python.git
-cd agentmemory-python
+git clone https://github.com/Yash030/agentcache-python.git
+cd agentcache-python
 ```
 
 Expect: the directory exists with `src/app.py` inside.
@@ -44,7 +44,7 @@ Or run in a separate terminal: `python src/app.py`
 Wait until it is reachable:
 
 ```bash
-curl -fsS http://localhost:3111/agentmemory/livez
+curl -fsS http://localhost:3111/agentcache/livez
 ```
 
 Expect: `{"status": "ok"}`. On first run the BM25 index initializes in the background; this takes under a second.
@@ -53,12 +53,12 @@ Expect: `{"status": "ok"}`. On first run the BM25 index initializes in the backg
 
 ```bash
 # Save a memory
-curl -X POST http://localhost:3111/agentmemory/remember \
+curl -X POST http://localhost:3111/agentcache/remember \
   -H "Content-Type: application/json" \
-  -d '{"content":"agentmemory-python install verification probe","concepts":["install-check"]}'
+  -d '{"content":"agentcache-python install verification probe","concepts":["install-check"]}'
 
 # Recall it
-curl -X POST http://localhost:3111/agentmemory/search \
+curl -X POST http://localhost:3111/agentcache/search \
   -H "Content-Type: application/json" \
   -d '{"query":"install verification probe","limit":5}'
 ```
@@ -67,18 +67,18 @@ Expect: first call returns `{"id": "...", "success": true}`, second returns resu
 
 ## 5. Wire MCP into the calling agent
 
-Detect which agent is running this runbook, then add agentmemory-python to its MCP config.
+Detect which agent is running this runbook, then add agentcache-python to its MCP config.
 
 ### Standard MCP block (Cursor, Claude Desktop, Cline, Windsurf, Gemini CLI)
 
 Merge this into the agent's `mcpServers` object:
 
 ```json
-"agentmemory": {
+"agentcache": {
   "command": "npx",
-  "args": ["-y", "@agentmemory/mcp"],
+  "args": ["-y", "@agentcache/mcp"],
   "env": {
-    "AGENTMEMORY_URL": "http://localhost:3111"
+    "AGENTCACHE_URL": "http://localhost:3111"
   }
 }
 ```
@@ -88,11 +88,11 @@ Merge this into the agent's `mcpServers` object:
 Add to `~/.claude.json` under `mcpServers`:
 
 ```json
-"agentmemory": {
+"agentcache": {
   "command": "npx",
-  "args": ["-y", "@agentmemory/mcp"],
+  "args": ["-y", "@agentcache/mcp"],
   "env": {
-    "AGENTMEMORY_URL": "http://localhost:3111"
+    "AGENTCACHE_URL": "http://localhost:3111"
   }
 }
 ```
@@ -101,17 +101,17 @@ Then reload MCP: run `/mcp` in Claude Code.
 
 ### Any agent — verify tool count
 
-After wiring, the agent should list agentmemory's tools. With the server running you should see 16 tools (e.g. `memory_save`, `memory_smart_search`, `memory_sessions`).
+After wiring, the agent should list agentcache's tools. With the server running you should see 16 tools (e.g. `memory_save`, `memory_smart_search`, `memory_sessions`).
 
-If you see 0 tools or an error, check that `python src/app.py` is running and `AGENTMEMORY_URL` points at it.
+If you see 0 tools or an error, check that `python src/app.py` is running and `AGENTCACHE_URL` points at it.
 
 ## 6. Setting up agent hooks
 
-Agent hooks post observations to agentmemory automatically on every tool use, command, or edit — no manual calls required. Hook scripts live in the [`hooks/`](hooks/) directory.
+Agent hooks post observations to agentcache automatically on every tool use, command, or edit — no manual calls required. Hook scripts live in the [`hooks/`](hooks/) directory.
 
 ### Claude Code (`hooks/claude-code-hook.sh`)
 
-Add a `PostToolUse` hook to `.claude/settings.json`. The hook script reads `AGENTMEMORY_URL` and `AGENTMEMORY_SECRET` from your shell environment, so no secrets are embedded in the config file.
+Add a `PostToolUse` hook to `.claude/settings.json`. The hook script reads `AGENTCACHE_URL` and `AGENTCACHE_SECRET` from your shell environment, so no secrets are embedded in the config file.
 
 ```json
 {
@@ -134,8 +134,8 @@ Add a `PostToolUse` hook to `.claude/settings.json`. The hook script reads `AGEN
 Set the required environment variables before starting Claude Code:
 
 ```bash
-export AGENTMEMORY_URL=http://127.0.0.1:3111
-export AGENTMEMORY_SECRET=your-secret-here   # omit if no auth set
+export AGENTCACHE_URL=http://127.0.0.1:3111
+export AGENTCACHE_SECRET=your-secret-here   # omit if no auth set
 ```
 
 The script picks up `$PWD` as `folderPath` and `$CLAUDE_AGENT_ID` (falling back to `"claude-code"`) as `agentId`.
@@ -151,7 +151,7 @@ const { logObservation } = require('/path/to/hooks/cursor-hook.js');
 logObservation(`Tool: ${toolName}\nInput: ${JSON.stringify(toolInput)}`);
 ```
 
-The module reads `AGENTMEMORY_URL`, `AGENTMEMORY_SECRET`, and `AGENTMEMORY_AGENT_ID` from `process.env`. Set them in your shell profile or in Cursor's environment settings.
+The module reads `AGENTCACHE_URL`, `AGENTCACHE_SECRET`, and `AGENTCACHE_AGENT_ID` from `process.env`. Set them in your shell profile or in Cursor's environment settings.
 
 ### PowerShell terminal (`hooks/powershell-hook.ps1`)
 
@@ -164,24 +164,24 @@ Add a single dot-source line to your PowerShell `$PROFILE` to activate automatic
 Set the required variables in `$PROFILE` before the dot-source line:
 
 ```powershell
-$env:AGENTMEMORY_URL      = "http://127.0.0.1:3111"
-$env:AGENTMEMORY_SECRET   = "your-secret-here"   # omit if no auth set
-$env:AGENTMEMORY_AGENT_ID = "powershell"
+$env:AGENTCACHE_URL      = "http://127.0.0.1:3111"
+$env:AGENTCACHE_SECRET   = "your-secret-here"   # omit if no auth set
+$env:AGENTCACHE_AGENT_ID = "powershell"
 ```
 
-The hook installs a PSReadLine `CommandValidationHandler` that fires a background job on every command you run. If PSReadLine is not available, call `Send-AgentMemoryObservation -Text "..."` manually.
+The hook installs a PSReadLine `CommandValidationHandler` that fires a background job on every command you run. If PSReadLine is not available, call `Send-AgentCacheObservation -Text "..."` manually.
 
 ### `.env` file format
 
-All hooks and the server itself read credentials from `~/.agentmemory/.env`. Create this file if it doesn't exist:
+All hooks and the server itself read credentials from `~/.agentcache/.env`. Create this file if it doesn't exist:
 
 ```
 III_REST_PORT=3111
-AGENTMEMORY_SECRET=your-secret-here
+AGENTCACHE_SECRET=your-secret-here
 GEMINI_API_KEY=your-gemini-key-here
 ```
 
-The server loads this file on startup. Hook scripts read the same variables from your shell environment (export them from your profile after sourcing `~/.agentmemory/.env`, or use `direnv` / `dotenv` tooling).
+The server loads this file on startup. Hook scripts read the same variables from your shell environment (export them from your profile after sourcing `~/.agentcache/.env`, or use `direnv` / `dotenv` tooling).
 
 ## 7. Open the viewer (optional)
 
@@ -200,8 +200,8 @@ The viewer shows live sessions, memories, and the knowledge graph.
 Vector search finds memories semantically, not just by keyword. Enable it with a free Gemini API key:
 
 ```bash
-mkdir -p ~/.agentmemory
-echo "GEMINI_API_KEY=your-key-here" >> ~/.agentmemory/.env
+mkdir -p ~/.agentcache
+echo "GEMINI_API_KEY=your-key-here" >> ~/.agentcache/.env
 ```
 
 Restart the server after adding the key. The viewer's search bar will now use hybrid BM25 + vector retrieval.
@@ -211,9 +211,9 @@ Restart the server after adding the key. The viewer's search bar will now use hy
 LLM compression makes each observation richer and more searchable. Requires an LLM API key:
 
 ```bash
-# Add to ~/.agentmemory/.env
+# Add to ~/.agentcache/.env
 ANTHROPIC_API_KEY=your-key   # or OPENAI_API_KEY or GEMINI_API_KEY
-AGENTMEMORY_AUTO_COMPRESS=true
+AGENTCACHE_AUTO_COMPRESS=true
 ```
 
 ## Lifecycle
@@ -223,11 +223,11 @@ AGENTMEMORY_AUTO_COMPRESS=true
 pkill -f "python src/app.py"
 
 # Check what's stored
-curl http://localhost:3111/agentmemory/sessions
-curl http://localhost:3111/agentmemory/memories
+curl http://localhost:3111/agentcache/sessions
+curl http://localhost:3111/agentcache/memories
 
 # Health check
-curl http://localhost:3111/agentmemory/livez
+curl http://localhost:3111/agentcache/livez
 ```
 
 ## Troubleshooting
@@ -235,18 +235,18 @@ curl http://localhost:3111/agentmemory/livez
 | Symptom | Fix |
 |---------|-----|
 | `ModuleNotFoundError: No module named 'flask'` | Run `pip install -r requirements.txt` |
-| `Address already in use` on port 3111 | Set `III_REST_PORT=3112` in `~/.agentmemory/.env` and restart |
+| `Address already in use` on port 3111 | Set `III_REST_PORT=3112` in `~/.agentcache/.env` and restart |
 | `/livez` never returns | Check `python src/app.py` stderr for import errors |
-| 0 tools in agent | Confirm `AGENTMEMORY_URL=http://localhost:3111` and the server is running |
-| `401 Unauthorized` | Set `AGENTMEMORY_SECRET` env var in the MCP config to match `~/.agentmemory/.env` |
-| Vector search not working | Add `GEMINI_API_KEY` to `~/.agentmemory/.env` and restart |
+| 0 tools in agent | Confirm `AGENTCACHE_URL=http://localhost:3111` and the server is running |
+| `401 Unauthorized` | Set `AGENTCACHE_SECRET` env var in the MCP config to match `~/.agentcache/.env` |
+| Vector search not working | Add `GEMINI_API_KEY` to `~/.agentcache/.env` and restart |
 | Windows Python path issue | Use `python3` instead of `python`, or use WSL2 |
 
 ## Report success
 
 Report back:
 
-- agentmemory-python server running on port 3111
+- agentcache-python server running on port 3111
 - MCP wired into the agent, tool count visible
 - Save and recall round-trip returned the probe memory
 - Viewer available at http://localhost:3111/viewer

README.md

@@ -1,5 +1,5 @@
 ---
-title: AgentMemory Python
+title: AgentCache Python
 emoji: 🧠
 colorFrom: blue
 colorTo: indigo
@@ -7,7 +7,7 @@ sdk: docker
 pinned: false
 ---
 
-<h1 align="center">agentmemory-python</h1>
+<h1 align="center">agentcache-python</h1>
 
 <p align="center">
   <strong>Persistent memory for AI coding agents — pure Python, zero external databases.</strong><br/>
@@ -49,14 +49,14 @@ pinned: false
 
 ## What Is This?
 
-**agentmemory-python** is a Python reimplementation of the [agentmemory](https://github.com/rohitg00/agentmemory) 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.
+**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 agentmemory
+- **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.
 
@@ -68,8 +68,8 @@ Your agent captures every tool call, stores them as observations, compresses the
 
 ```bash
 # Clone
-git clone https://github.com/Yash030/agentmemory-python.git
-cd agentmemory-python
+git clone https://github.com/Yash030/agentcache-python.git
+cd agentcache-python
 
 # Install dependencies (no build step)
 pip install -r requirements.txt
@@ -84,16 +84,16 @@ Server starts on **http://localhost:3111**. Open the viewer at http://localhost:
 
 ```bash
 # Health check
-curl http://localhost:3111/agentmemory/livez
+curl http://localhost:3111/agentcache/livez
 # {"status": "ok"}
 
 # Save a memory
-curl -X POST http://localhost:3111/agentmemory/remember \
+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/agentmemory/search \
+curl -X POST http://localhost:3111/agentcache/search \
   -H "Content-Type: application/json" \
   -d '{"query": "authentication middleware", "limit": 5}'
 ```
@@ -112,7 +112,7 @@ curl -X POST http://localhost:3111/agentmemory/search \
 | 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 | ⚙️ | `AGENTMEMORY_AUTO_COMPRESS=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 |
@@ -135,18 +135,18 @@ Inspired by how human memory works — raw experience → compressed episodes
 
 ## MCP Integration
 
-Wire agentmemory-python into your agent's MCP config. It speaks the same MCP protocol as the Node.js original.
+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": {
-    "agentmemory": {
+    "agentcache": {
       "command": "npx",
-      "args": ["-y", "@agentmemory/mcp"],
+      "args": ["-y", "@agentcache/mcp"],
       "env": {
-        "AGENTMEMORY_URL": "http://localhost:3111"
+        "AGENTCACHE_URL": "http://localhost:3111"
       }
     }
   }
@@ -158,16 +158,16 @@ Wire agentmemory-python into your agent's MCP config. It speaks the same MCP pro
 Paste this prompt and your agent will wire everything:
 
 ```
-Start agentmemory-python: run `python src/app.py` from the agentmemory-python directory.
+Start agentcache-python: run `python src/app.py` from the agentcache-python directory.
 Then add this MCP server to ~/.claude.json under mcpServers:
 {
-  "agentmemory": {
+  "agentcache": {
     "command": "npx",
-    "args": ["-y", "@agentmemory/mcp"],
-    "env": { "AGENTMEMORY_URL": "http://localhost:3111" }
+    "args": ["-y", "@agentcache/mcp"],
+    "env": { "AGENTCACHE_URL": "http://localhost:3111" }
   }
 }
-Verify with: curl http://localhost:3111/agentmemory/livez
+Verify with: curl http://localhost:3111/agentcache/livez
 Open the viewer at: http://localhost:3111/viewer
 ```
 
@@ -193,7 +193,7 @@ Open the viewer at: http://localhost:3111/viewer
 | `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 memory to long-term storage |
+| `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 |
@@ -211,7 +211,7 @@ Open the viewer at: http://localhost:3111/viewer
 
 ## API Reference
 
-Base URL: `http://localhost:3111/agentmemory`
+Base URL: `http://localhost:3111/agentcache`
 
 ### Health
 
@@ -304,7 +304,7 @@ Base URL: `http://localhost:3111/agentmemory`
 
 ## Configuration
 
-Create `~/.agentmemory/.env` (no `export` prefix needed):
+Create `~/.agentcache/.env` (no `export` prefix needed):
 
 ```env
 # Server port
@@ -322,22 +322,22 @@ ANTHROPIC_API_KEY=your-anthropic-key
 # LLM-powered features (disabled by default — spend tokens)
 CONSOLIDATION_ENABLED=true
 GRAPH_EXTRACTION_ENABLED=true
-AGENTMEMORY_AUTO_COMPRESS=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
-AGENTMEMORY_SECRET=your-secret
+AGENTCACHE_SECRET=your-secret
 
 # Agent scope isolation
 AGENT_ID=my-agent
-AGENTMEMORY_AGENT_SCOPE=isolated   # only see this agent's data
+AGENTCACHE_AGENT_SCOPE=isolated   # only see this agent's data
 
 # HuggingFace sync
 HF_TOKEN=your-hf-token
-AGENTMEMORY_DATASET_REPO=username/agentmemory-data
+AGENTCACHE_DATASET_REPO=username/agentcache-data
 ```
 
 ### Full Variable Reference
@@ -346,14 +346,14 @@ AGENTMEMORY_DATASET_REPO=username/agentmemory-data
 |----------|---------|---------|
 | `III_REST_PORT` / `PORT` | `3111` | API server port |
 | `GEMINI_API_KEY` / `GOOGLE_API_KEY` | — | Enables 768-dim vector search |
-| `AGENTMEMORY_SECRET` | — | Bearer token auth on all endpoints |
+| `AGENTCACHE_SECRET` | — | Bearer token auth on all endpoints |
 | `AGENT_ID` | — | Default agent ID for scope isolation |
-| `AGENTMEMORY_AGENT_SCOPE=isolated` | — | Filters data to current `AGENT_ID` |
+| `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) |
-| `AGENTMEMORY_AUTO_COMPRESS` | `false` | LLM observation compression |
+| `AGENTCACHE_AUTO_COMPRESS` | `false` | LLM observation compression |
 
 ---
 
@@ -381,17 +381,17 @@ This project is designed to run as a HuggingFace Space. Data is stored in an HF
 ### Setup
 
 1. Fork this repo as a HuggingFace Space (SDK: Docker)
-2. Create a dataset repo (e.g. `your-username/agentmemory-data`)
+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 |
-   | `AGENTMEMORY_DATASET_REPO` | `your-username/agentmemory-data` |
-   | `AGENTMEMORY_SECRET` | A random secret (optional but recommended) |
+   | `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 `agentmemory.db` from the dataset repo, and starts the server
+4. The Space boots, restores `agentcache.db` from the dataset repo, and starts the server
 
 ### How sync works
 
@@ -403,7 +403,7 @@ python sync.py
 
 # Environment for sync
 HF_TOKEN=...
-AGENTMEMORY_DATASET_REPO=username/agentmemory-data
+AGENTCACHE_DATASET_REPO=username/agentcache-data
 ```
 
 ---
@@ -411,7 +411,7 @@ AGENTMEMORY_DATASET_REPO=username/agentmemory-data
 ## Architecture
 
 ```
-agentmemory-python/
+agentcache-python/
 ├── src/
 │   ├── app.py          Flask server — all endpoints, WebSocket broadcaster
 │   ├── db.py           SQLite StateKV — WAL mode, audit_log table
@@ -427,7 +427,7 @@ agentmemory-python/
 
 ### Database layout
 
-Two SQLite tables in `~/.agentmemory/agentmemory.db`:
+Two SQLite tables in `~/.agentcache/agentcache.db`:
 
 ```sql
 -- All data lives here, namespaced by scope
@@ -460,9 +460,9 @@ Query
 
 ---
 
-## vs Original agentmemory
+## vs Original agentcache
 
-| | agentmemory (Node.js) | agentmemory-python |
+| | agentcache (Node.js) | agentcache-python |
 |---|---|---|
 | Runtime | Node.js 20+ | Python 3.10+ |
 | Storage | Dolt SQL (git-versioned MySQL) | SQLite WAL (single file) |
@@ -473,7 +473,7 @@ Query
 | 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 @agentmemory/agentmemory` | `pip install -r requirements.txt` |
+| 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.
 

agentmemory.md → agentcache.md

@@ -1,4 +1,4 @@
-# AgentMemory Automation & Client Hook Roundabout
+# AgentCache Automation & Client Hook Roundabout
 
 This file documents the technical details and configurations for automating memory sessions, observations, and prompt-context syncing in environments that lack native client-side hook runners.
 
@@ -9,7 +9,7 @@ For standard command shells that do not have custom plugins (such as PowerShell)
 * **Profile File**: `D:\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`
 * **Automation Mechanism**:
   1. **Prompt Redefinition**: Overrides the default PowerShell `prompt` function to retrieve the last executed command from the session history (`Get-History`).
-  2. **Asynchronous Dispatch**: Uses PowerShell's `Start-Job` to send the command, execution status, and duration to the Hugging Face Space database (`https://yash030-agentmemory-python.hf.space/agentmemory/observe`) in the background, keeping terminal prompts lag-free.
+  2. **Asynchronous Dispatch**: Uses PowerShell's `Start-Job` to send the command, execution status, and duration to the Hugging Face Space database (`https://yash030-agentcache-python.hf.space/agentcache/observe`) in the background, keeping terminal prompts lag-free.
   3. **Interactive Shield**: Wraps the prompts and startup session creation in `if (-not [Console]::IsInputRedirected)` so background script executions or tool runners do not pollute the database.
   4. **Active Session Reuse**: On console startup, checks for a cached session ID in `current_session.txt` and reuses it to prevent session clutter.
 

docker-compose.yml

@@ -22,8 +22,8 @@ services:
     # refactored to register as a sandboxed worker.
     #
     # Override per-shell or via .env file:
-    #   AGENTMEMORY_III_VERSION=0.11.7 docker compose up
-    image: iiidev/iii:${AGENTMEMORY_III_VERSION:-0.11.2}
+    #   AGENTCACHE_III_VERSION=0.11.7 docker compose up
+    image: iiidev/iii:${AGENTCACHE_III_VERSION:-${AGENTMEMORY_III_VERSION:-0.11.2}}
     user: "65532:65532"
     depends_on:
       iii-init:

pyproject.toml

@@ -3,9 +3,9 @@ requires = ["setuptools>=68", "wheel"]
 build-backend = "setuptools.backends.legacy:build"
 
 [project]
-name = "agentmemory"
+name = "agentcache"
 version = "0.9.8"
-description = "A Python REST + WebSocket + MCP memory server for AI agents, backed by SQLite"
+description = "A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
@@ -28,7 +28,7 @@ local-embeddings = [
 ]
 
 [project.scripts]
-agentmemory = "src.cli:main"
+agentcache = "src.cli:main"
 
 [tool.setuptools.packages.find]
 where = ["."]

src/app.py

@@ -18,7 +18,9 @@ if __name__ == "__main__":
 
 
 def _load_env() -> None:
-    env_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".env")
+    env_path = os.path.join(os.path.expanduser("~"), ".agentcache", ".env")
+    if not os.path.exists(env_path):
+        env_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".env")
     if not os.path.exists(env_path):
         return
     try:
@@ -47,8 +49,8 @@ def create_app() -> Flask:
     global kv, embedding_provider, persistence
 
     # Check security credentials
-    if not os.getenv("AGENTMEMORY_SECRET"):
-        print("[security] WARNING: AGENTMEMORY_SECRET is not set! All API endpoints are publicly accessible without authentication.")
+    if not os.getenv("AGENTCACHE_SECRET") and not os.getenv("AGENTMEMORY_SECRET"):
+        print("[security] WARNING: AGENTCACHE_SECRET/AGENTMEMORY_SECRET is not set! All API endpoints are publicly accessible without authentication.")
 
     import search as search_mod
     import functions
@@ -59,10 +61,10 @@ def create_app() -> Flask:
     kv = StateKV()
 
     # 2. Embedding provider — auto-select by priority (D5.3):
-    #    GEMINI_API_KEY → OPENAI_API_KEY → AGENTMEMORY_LOCAL_EMBEDDING_MODEL → BM25-only
+    #    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")
-    local_model = os.getenv("AGENTMEMORY_LOCAL_EMBEDDING_MODEL")
+    local_model = os.getenv("AGENTCACHE_LOCAL_EMBEDDING_MODEL") or os.getenv("AGENTMEMORY_LOCAL_EMBEDDING_MODEL")
 
     if api_key:
         try:
@@ -118,7 +120,7 @@ def create_app() -> Flask:
 
     @sock.route("/stream/mem-live/viewer")
     def stream_viewer(ws):
-        secret = os.getenv("AGENTMEMORY_SECRET")
+        secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
         if secret:
             token = request.args.get("token") or request.args.get("secret")
             if not token or not hmac.compare_digest(
@@ -150,6 +152,7 @@ def create_app() -> Flask:
 
     @flask_app.route("/")
     @flask_app.route("/viewer")
+    @flask_app.route("/agentcache/viewer")
     @flask_app.route("/agentmemory/viewer")
     def serve_viewer():
         try:
@@ -161,7 +164,7 @@ def create_app() -> Flask:
     def serve_favicon():
         return send_from_directory(os.path.join(_base_dir, "viewer"), "favicon.svg")
 
-    # 7. CORS after_request — D2.1: configurable via AGENTMEMORY_CORS_ORIGINS env var
+    # 7. CORS after_request — D2.1: configurable via AGENTCACHE_CORS_ORIGINS env var
     # Default allows localhost, 127.0.0.1, HuggingFace Spaces, vscode-webview://, chrome-extension://
     # Wildcard entries like "*.hf.space" match any subdomain via suffix check.
     _default_cors = (
@@ -169,7 +172,7 @@ def create_app() -> Flask:
         "https://huggingface.co,https://*.hf.space,"
         "vscode-webview://*,chrome-extension://*"
     )
-    _cors_origins_raw = os.getenv("AGENTMEMORY_CORS_ORIGINS", _default_cors)
+    _cors_origins_raw = os.getenv("AGENTCACHE_CORS_ORIGINS") or os.getenv("AGENTMEMORY_CORS_ORIGINS") or _default_cors
 
     def _parse_cors_origins(raw: str):
         """Return (exact_set, suffix_list) for efficient origin matching."""

src/{memory → cache}/__init__.py

@@ -1,5 +1,5 @@
 """
-src/memory/ — Core business logic package for agentmemory-python.
+src/cache/ — Core business logic package for agentcache-python.
 
 Sub-modules:
   observe   — folder_observe(), observe(), build_synthetic_compression(), strip_private_data()

src/cli.py

@@ -1,11 +1,11 @@
 #!/usr/bin/env python3
 """
-agentmemory CLI entrypoint.
+agentcache CLI entrypoint.
 
 Commands:
-  agentmemory serve [--port PORT] [--host HOST]
-  agentmemory migrate [--dry-run]
-  agentmemory export [--output FILE]
+  agentcache serve [--port PORT] [--host HOST]
+  agentcache migrate [--dry-run]
+  agentcache export [--output FILE]
 """
 
 import argparse
@@ -20,7 +20,7 @@ def cmd_serve(args) -> None:
     sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
     from app import create_app
     flask_app = create_app()
-    print(f"[cli] Starting agentmemory on {args.host}:{args.port}")
+    print(f"[cli] Starting agentcache on {args.host}:{args.port}")
     flask_app.run(host=args.host, port=args.port, debug=False)
 
 
@@ -67,13 +67,13 @@ def cmd_export(args) -> None:
 
 def main() -> None:
     parser = argparse.ArgumentParser(
-        prog="agentmemory",
-        description="agentmemory — AI agent memory server",
+        prog="agentcache",
+        description="agentcache — AI agent cache server",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
     # serve
-    serve_parser = subparsers.add_parser("serve", help="Start the memory server")
+    serve_parser = subparsers.add_parser("serve", help="Start the cache server")
     serve_parser.add_argument("--port", type=int, default=int(os.getenv("III_REST_PORT", "3111")))
     serve_parser.add_argument("--host", default="0.0.0.0")
 

src/connect.py

@@ -124,22 +124,22 @@ class ClaudeCodeAdapter:
         next_cfg = existing.copy()
         servers = next_cfg.get("mcpServers", {})
 
-        already_has = "agentmemory" in servers
+        already_has = "agentcache" in servers
         if already_has and not args.force:
             print(f"[OK] Claude Code already wired in {claude_json}")
         else:
             if args.dry_run:
-                print(f"[dry-run] Would write mcpServers.agentmemory in {claude_json}")
+                print(f"[dry-run] Would write mcpServers.agentcache in {claude_json}")
             else:
                 backup = backup_file(claude_json, "claude-code")
                 if backup:
                     print(f"Backed up configuration to {backup}")
                 
-                env = {"AGENTMEMORY_URL": os.environ.get("AGENTMEMORY_URL", "http://localhost:3111")}
-                secret = os.environ.get("AGENTMEMORY_SECRET")
+                env = {"AGENTCACHE_URL": os.environ.get("AGENTCACHE_URL") or os.environ.get("AGENTMEMORY_URL") or "http://localhost:3111"}
+                secret = os.environ.get("AGENTCACHE_SECRET") or os.environ.get("AGENTMEMORY_SECRET")
                 if secret:
-                    env["AGENTMEMORY_SECRET"] = secret
-                servers["agentmemory"] = {
+                    env["AGENTCACHE_SECRET"] = secret
+                servers["agentcache"] = {
                     "command": sys.executable,
                     "args": [mcp_stdio_path],
                     "env": env
@@ -179,17 +179,17 @@ class CodexAdapter:
         codex_toml = os.path.join(get_home_dir(), ".codex", "config.toml")
         mcp_stdio_path = get_mcp_stdio_path()
 
-        url = os.environ.get("AGENTMEMORY_URL", "http://localhost:3111")
-        secret = os.environ.get("AGENTMEMORY_SECRET")
+        url = os.environ.get("AGENTCACHE_URL") or os.environ.get("AGENTMEMORY_URL") or "http://localhost:3111"
+        secret = os.environ.get("AGENTCACHE_SECRET") or os.environ.get("AGENTMEMORY_SECRET")
         toml_block = f"""
-[mcp_servers.agentmemory]
+[mcp_servers.agentcache]
 command = "{sys.executable.replace('\\', '/')}"
 args = ["{mcp_stdio_path.replace('\\', '/')}"]
-[mcp_servers.agentmemory.env]
-AGENTMEMORY_URL = "{url}"
+[mcp_servers.agentcache.env]
+AGENTCACHE_URL = "{url}"
 """
         if secret:
-            toml_block += f'AGENTMEMORY_SECRET = "{secret}"\n'
+            toml_block += f'AGENTCACHE_SECRET = "{secret}"\n'
 
         exists = os.path.exists(codex_toml)
         current = ""
@@ -197,12 +197,12 @@ AGENTMEMORY_URL = "{url}"
             with open(codex_toml, "r", encoding="utf-8") as f:
                 current = f.read()
 
-        wired = "[mcp_servers.agentmemory]" in current
+        wired = "[mcp_servers.agentcache]" in current
         if wired and not args.force:
             print(f"[OK] Codex CLI already wired in {codex_toml}")
         else:
             if args.dry_run:
-                print(f"[dry-run] Would write [mcp_servers.agentmemory] block to {codex_toml}")
+                print(f"[dry-run] Would write [mcp_servers.agentcache] block to {codex_toml}")
             else:
                 backup = backup_file(codex_toml, "codex", "toml")
                 if backup:
@@ -216,10 +216,10 @@ AGENTMEMORY_URL = "{url}"
                     skipping = False
                     for line in lines:
                         trimmed = line.strip()
-                        if trimmed == "[mcp_servers.agentmemory]" or trimmed == "[mcp_servers.agentmemory.env]":
+                        if trimmed == "[mcp_servers.agentcache]" or trimmed == "[mcp_servers.agentcache.env]":
                             skipping = True
                             continue
-                        if skipping and trimmed.startswith("[") and trimmed != "[mcp_servers.agentmemory.env]":
+                        if skipping and trimmed.startswith("[") and trimmed != "[mcp_servers.agentcache.env]":
                             skipping = False
                         if not skipping:
                             out.append(line)
@@ -258,7 +258,7 @@ class HermesAdapter:
         return os.path.exists(hermes_dir)
 
     def install(self, args):
-        dest_dir = os.path.join(get_home_dir(), ".hermes", "plugins", "agentmemory")
+        dest_dir = os.path.join(get_home_dir(), ".hermes", "plugins", "agentcache")
         src_dir = os.path.dirname(os.path.abspath(__file__))
         project_root = os.path.dirname(src_dir)
         hermes_src = os.path.join(project_root, "integrations", "hermes")
@@ -277,14 +277,14 @@ class HermesAdapter:
                 shutil.rmtree(dest_dir)
             
             shutil.copytree(hermes_src, dest_dir)
-            print(f"[OK] Copied Hermes memory provider plugin to {dest_dir}")
+            print(f"[OK] Copied Hermes cache provider plugin to {dest_dir}")
             print("To finish configuration, add to ~/.hermes/config.yaml:")
             print("  mcp_servers:")
-            print("    agentmemory:")
+            print("    agentcache:")
             print("      command: python")
             print(f'      args: ["{get_mcp_stdio_path()}"]')
-            print("  memory:")
-            print("    provider: agentmemory")
+            print("  cache:")
+            print("    provider: agentcache")
 
 class AntigravityAdapter:
     name = "antigravity"
@@ -310,22 +310,22 @@ class AntigravityAdapter:
         next_cfg = existing.copy()
         servers = next_cfg.get("mcpServers", {})
 
-        already_has = "agentmemory" in servers
+        already_has = "agentcache" in servers
         if already_has and not args.force:
             print(f"[OK] Antigravity already wired in {mcp_config_path}")
         else:
             if args.dry_run:
-                print(f"[dry-run] Would write mcpServers.agentmemory in {mcp_config_path}")
+                print(f"[dry-run] Would write mcpServers.agentcache in {mcp_config_path}")
             else:
                 backup = backup_file(mcp_config_path, "antigravity")
                 if backup:
                     print(f"Backed up config to {backup}")
                 
-                env = {"AGENTMEMORY_URL": os.environ.get("AGENTMEMORY_URL", "http://localhost:3111")}
-                secret = os.environ.get("AGENTMEMORY_SECRET")
+                env = {"AGENTCACHE_URL": os.environ.get("AGENTCACHE_URL") or os.environ.get("AGENTMEMORY_URL") or "http://localhost:3111"}
+                secret = os.environ.get("AGENTCACHE_SECRET") or os.environ.get("AGENTMEMORY_SECRET")
                 if secret:
-                    env["AGENTMEMORY_SECRET"] = secret
-                servers["agentmemory"] = {
+                    env["AGENTCACHE_SECRET"] = secret
+                servers["agentcache"] = {
                     "command": sys.executable,
                     "args": [mcp_stdio_path],
                     "env": env
@@ -350,22 +350,22 @@ class KiroAdapter:
         next_cfg = existing.copy()
         servers = next_cfg.get("mcpServers", {})
 
-        already_has = "agentmemory" in servers
+        already_has = "agentcache" in servers
         if already_has and not args.force:
             print(f"[OK] Kiro already wired in {mcp_config_path}")
         else:
             if args.dry_run:
-                print(f"[dry-run] Would write mcpServers.agentmemory in {mcp_config_path}")
+                print(f"[dry-run] Would write mcpServers.agentcache in {mcp_config_path}")
             else:
                 backup = backup_file(mcp_config_path, "kiro")
                 if backup:
                     print(f"Backed up config to {backup}")
                 
-                env = {"AGENTMEMORY_URL": os.environ.get("AGENTMEMORY_URL", "http://localhost:3111")}
-                secret = os.environ.get("AGENTMEMORY_SECRET")
+                env = {"AGENTCACHE_URL": os.environ.get("AGENTCACHE_URL") or os.environ.get("AGENTMEMORY_URL") or "http://localhost:3111"}
+                secret = os.environ.get("AGENTCACHE_SECRET") or os.environ.get("AGENTMEMORY_SECRET")
                 if secret:
-                    env["AGENTMEMORY_SECRET"] = secret
-                servers["agentmemory"] = {
+                    env["AGENTCACHE_SECRET"] = secret
+                servers["agentcache"] = {
                     "command": sys.executable,
                     "args": [mcp_stdio_path],
                     "env": env
@@ -383,26 +383,26 @@ class RulesGeneratorAdapter:
         return True
 
     def install(self, args):
-        rule_content = """# Agent Memory Rules
+        rule_content = """# Agent Cache Rules
 
-This workspace is integrated with long-term semantic memory via `agentmemory-python`.
-You must act as your own memory manager by calling the memory MCP tools at critical boundaries.
+This workspace is integrated with long-term semantic memory via `agentcache-python`.
+You must act as your own cache manager by calling the cache MCP tools at critical boundaries.
 
 ## Rules & Workflow
 
 1. **Initial Search (Prefetch Context)**:
-   At the start of every session or new task, immediately call `memory_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
-   - Example: `memory_smart_search(query="jwt token rotation logic")`
+   At the start of every session or new task, immediately call `cache_smart_search` with terms related to the current objective. This retrieves past architecture patterns, preferences, bug fixes, or lessons.
+   - Example: `cache_smart_search(query="jwt token rotation logic")`
 
 2. **Lessons & Insights Capture**:
    When you successfully debug a complex error, discover an undocumented requirement, or establish a convention, persist it:
-   - Call `memory_lesson_save` to record lessons that improve your coding capabilities. Duplicate saves strengthen confidence scores.
-   - Call `memory_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
+   - Call `cache_lesson_save` to record lessons that improve your coding capabilities. Duplicate saves strengthen confidence scores.
+   - Call `cache_save` to save long-term structural facts. Always extract 2-5 specific lowercased tags (e.g. `auth-flow`, `refresh-token`) as concepts.
 
 3. **Checklist Before Ending**:
    Before stating a task is complete:
    - Reflect on whether any lessons learned should be saved.
-   - Call `memory_reflect` to automatically distribute observations into slots if needed.
+   - Call `cache_reflect` to automatically distribute observations into slots if needed.
 """
         cwd = os.getcwd()
         
@@ -435,7 +435,7 @@ ADAPTERS = [
 ]
 
 def main():
-    parser = argparse.ArgumentParser(description="Wired agentmemory MCP and Hooks into client agents.")
+    parser = argparse.ArgumentParser(description="Wired agentcache MCP and Hooks into client agents.")
     parser.add_argument("agent", nargs="?", choices=[a.name for a in ADAPTERS], help="Specify target agent.")
     parser.add_argument("--with-hooks", action="store_true", help="Install global workspace hook execution blocks (Claude/Codex).")
     parser.add_argument("--dry-run", action="store_true", help="Log proposed configuration modifications without writing.")

src/db.py

@@ -8,7 +8,7 @@ from typing import Dict, Any, List, Optional, TypeVar, Union
 
 T = TypeVar("T")
 
-DB_PATH = os.path.join(os.path.expanduser("~"), ".agentmemory", "agentmemory.db")
+DB_PATH = os.path.join(os.path.expanduser("~"), ".agentcache", "agentcache.db")
 
 
 class StateKV:

src/functions.py

@@ -409,10 +409,10 @@ def query_audit(
 # Image Store System
 # =====================================================================
 
-IMAGES_DIR = os.path.join(os.path.expanduser("~"), ".agentmemory", "images")
+IMAGES_DIR = os.path.join(os.path.expanduser("~"), ".agentcache", "images")
 
 def get_max_bytes() -> int:
-    return int(os.getenv("AGENTMEMORY_IMAGE_STORE_MAX_BYTES", 500 * 1024 * 1024))
+    return int(os.getenv("AGENTCACHE_IMAGE_STORE_MAX_BYTES") or os.getenv("AGENTMEMORY_IMAGE_STORE_MAX_BYTES") or 500 * 1024 * 1024)
 
 def is_managed_image_path(file_path: str) -> bool:
     if not file_path:
@@ -468,7 +468,7 @@ def delete_image(file_path: Optional[str]) -> int:
             os.remove(file_path)
             return size
     except Exception as e:
-        print(f"[agentmemory] Failed to delete image context: {e}")
+        print(f"[agentcache] Failed to delete image context: {e}")
     return 0
 
 def touch_image(file_path: str) -> None:
@@ -680,16 +680,16 @@ def commit_if_enabled(kv: StateKV, message: str, agent_id: Optional[str]) -> Opt
 
 
 def is_agent_scope_isolated() -> bool:
-    return os.getenv("AGENTMEMORY_AGENT_SCOPE") == "isolated"
+    return (os.getenv("AGENTCACHE_AGENT_SCOPE") or os.getenv("AGENTMEMORY_AGENT_SCOPE")) == "isolated"
 
 def is_auto_compress_enabled() -> bool:
-    return os.getenv("AGENTMEMORY_AUTO_COMPRESS") == "true"
+    return (os.getenv("AGENTCACHE_AUTO_COMPRESS") or os.getenv("AGENTMEMORY_AUTO_COMPRESS")) == "true"
 
 def is_slots_enabled() -> bool:
-    return os.getenv("AGENTMEMORY_SLOTS") == "true"
+    return (os.getenv("AGENTCACHE_SLOTS") or os.getenv("AGENTMEMORY_SLOTS")) == "true"
 
 def is_reflect_enabled() -> bool:
-    return os.getenv("AGENTMEMORY_REFLECT") == "true"
+    return (os.getenv("AGENTCACHE_REFLECT") or os.getenv("AGENTMEMORY_REFLECT")) == "true"
 
 def is_graph_extraction_enabled() -> bool:
     return os.getenv("GRAPH_EXTRACTION_ENABLED") == "true"
@@ -1825,8 +1825,8 @@ def context(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
     blocks.sort(key=lambda b: b.get("recency", 0), reverse=True)
 
-    header = f'<agentmemory-context project="{escape_xml_attr(project)}">'
-    footer = "</agentmemory-context>"
+    header = f'<agentcache-context project="{escape_xml_attr(project)}">'
+    footer = "</agentcache-context>"
     used_tokens = estimate_tokens(header) + estimate_tokens(footer)
 
     selected = []
@@ -1949,7 +1949,7 @@ def list_pinned_slots(kv: StateKV, project: Optional[str] = None) -> List[Dict[s
 def render_pinned_context(slots: List[Dict[str, Any]]) -> str:
     if not slots:
         return ""
-    lines = ["# agentmemory pinned slots", ""]
+    lines = ["# agentcache pinned slots", ""]
     for s in slots:
         lines.append(f"## {s['label']}")
         lines.append(s["content"].strip())
@@ -3006,7 +3006,7 @@ def health_check(kv: StateKV) -> Dict[str, Any]:
     db_size_bytes = 0
     wal_size_bytes = 0
     try:
-        sync_state_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".sync_state")
+        sync_state_path = os.path.join(os.path.expanduser("~"), ".agentcache", ".sync_state")
         if os.path.exists(sync_state_path):
             with open(sync_state_path, "r", encoding="utf-8") as _sf:
                 _sync = json.loads(_sf.read())

src/import_data.py

@@ -53,7 +53,7 @@ def import_old_data(old_db_path: str, kv: StateKV) -> bool:
             
     if count > 0:
         print("[import] Creating Dolt version commit...")
-        kv.commit_version("Import legacy AgentMemory database from Hugging Face", "system")
+        kv.commit_version("Import legacy AgentCache database from Hugging Face", "system")
 
     print(f"[import] Finished! Migrated {count} total records into Dolt SQL.")
     return True
@@ -61,8 +61,8 @@ def import_old_data(old_db_path: str, kv: StateKV) -> bool:
 
 if __name__ == "__main__":
     # Prioritize the restored HF data in the user's home folder, falling back to local workspace data
-    home_path = os.path.expanduser(os.path.join("~", ".agentmemory", "state_store.db"))
-    workspace_path = r"d:\Downloads\Projects\Other Projects\agentmemory\agentmemory\data\state_store.db"
+    home_path = os.path.expanduser(os.path.join("~", ".agentcache", "state_store.db"))
+    workspace_path = r"d:\Downloads\Projects\Other Projects\agentcache\agentcache\data\state_store.db"
     
     if os.path.exists(home_path):
         default_path = home_path

src/mcp_stdio.py

@@ -13,11 +13,11 @@ import json
 import os
 import requests
 
-BASE = os.getenv("AGENTMEMORY_URL", "http://127.0.0.1:3111").rstrip("/")
-if not BASE.endswith("/agentmemory"):
-    BASE = f"{BASE}/agentmemory"
+BASE = (os.getenv("AGENTCACHE_URL") or os.getenv("AGENTMEMORY_URL") or "http://127.0.0.1:3111").rstrip("/")
+if not BASE.endswith("/agentcache") and not BASE.endswith("/agentmemory"):
+    BASE = f"{BASE}/agentcache"
 
-_secret = os.getenv("AGENTMEMORY_SECRET")
+_secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
 
 
 def headers():
@@ -44,7 +44,7 @@ def handle(req):
             "result": {
                 "protocolVersion": "2024-11-05",
                 "capabilities": {"tools": {}},
-                "serverInfo": {"name": "agentmemory-local", "version": "0.9.8"}
+                "serverInfo": {"name": "agentcache-local", "version": "0.9.8"}
             }
         })
 

src/routes/graph.py

@@ -18,7 +18,7 @@ graph_bp = Blueprint("graph", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -36,9 +36,10 @@ def _get_kv():
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/graph
+# GET /agentcache/graph
 # ---------------------------------------------------------------------------
 
+@graph_bp.route("/agentcache/graph", methods=["GET"])
 @graph_bp.route("/agentmemory/graph", methods=["GET"])
 def api_graph():
     auth_err = _check_auth()
@@ -49,9 +50,10 @@ def api_graph():
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/graph/stats
+# GET /agentcache/graph/stats
 # ---------------------------------------------------------------------------
 
+@graph_bp.route("/agentcache/graph/stats", methods=["GET"])
 @graph_bp.route("/agentmemory/graph/stats", methods=["GET"])
 def api_graph_stats():
     auth_err = _check_auth()
@@ -67,9 +69,10 @@ def api_graph_stats():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/graph/query
+# POST /agentcache/graph/query
 # ---------------------------------------------------------------------------
 
+@graph_bp.route("/agentcache/graph/query", methods=["POST"])
 @graph_bp.route("/agentmemory/graph/query", methods=["POST"])
 def api_graph_query():
     auth_err = _check_auth()
@@ -84,9 +87,10 @@ def api_graph_query():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/graph/build
+# POST /agentcache/graph/build
 # ---------------------------------------------------------------------------
 
+@graph_bp.route("/agentcache/graph/build", methods=["POST"])
 @graph_bp.route("/agentmemory/graph/build", methods=["POST"])
 def api_graph_build():
     auth_err = _check_auth()

src/routes/health.py

@@ -18,7 +18,7 @@ health_bp = Blueprint("health", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -41,33 +41,36 @@ def _get_embedding_provider():
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/livez  (no auth required)
+# GET /agentcache/livez  (no auth required)
 # ---------------------------------------------------------------------------
 
+@health_bp.route("/agentcache/livez", methods=["GET"])
 @health_bp.route("/agentmemory/livez", methods=["GET"])
 def livez():
     port = int(os.getenv("III_REST_PORT", os.getenv("PORT", "3111")))
     return jsonify({
         "status": "ok",
-        "service": "agentmemory",
+        "service": "agentcache",
         "viewerPort": port,
         "viewerSkipped": False,
     })
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/health
+# GET /agentcache/health
 # ---------------------------------------------------------------------------
 
+@health_bp.route("/agentcache/health", methods=["GET"])
 @health_bp.route("/agentmemory/health", methods=["GET"])
 def health():
     return jsonify(functions.health_check(_get_kv()))
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/audit
+# GET /agentcache/audit
 # ---------------------------------------------------------------------------
 
+@health_bp.route("/agentcache/audit", methods=["GET"])
 @health_bp.route("/agentmemory/audit", methods=["GET"])
 def api_audit():
     auth_err = _check_auth()
@@ -81,9 +84,10 @@ def api_audit():
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/config/flags
+# GET /agentcache/config/flags
 # ---------------------------------------------------------------------------
 
+@health_bp.route("/agentcache/config/flags", methods=["GET"])
 @health_bp.route("/agentmemory/config/flags", methods=["GET"])
 def config_flags():
     auth_err = _check_auth()
@@ -118,14 +122,14 @@ def config_flags():
             "docsHref": "https://github.com/rohitg00/agentmemory#consolidation",
         },
         {
-            "key": "AGENTMEMORY_AUTO_COMPRESS",
+            "key": "AGENTCACHE_AUTO_COMPRESS",
             "label": "LLM-powered observation compression",
             "enabled": functions.is_auto_compress_enabled(),
             "default": False,
             "affects": ["Memories", "Timeline"],
             "needsLlm": True,
             "description": "Every observation is compressed by the LLM for richer summaries. OFF uses synthetic compression.",
-            "enableHow": "Set AGENTMEMORY_AUTO_COMPRESS=true.",
+            "enableHow": "Set AGENTCACHE_AUTO_COMPRESS=true.",
             "docsHref": "https://github.com/rohitg00/agentmemory/issues/138",
         },
     ]

src/routes/mcp.py

@@ -18,7 +18,7 @@ mcp_bp = Blueprint("mcp", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -49,9 +49,10 @@ def _parse_mcp_list_arg(arg_val):
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/mcp/tools
+# GET /agentcache/mcp/tools
 # ---------------------------------------------------------------------------
 
+@mcp_bp.route("/agentcache/mcp/tools", methods=["GET"])
 @mcp_bp.route("/agentmemory/mcp/tools", methods=["GET"])
 def mcp_tools_list():
     auth_err = _check_auth()
@@ -60,7 +61,7 @@ def mcp_tools_list():
 
     tools = [
         {
-            "name": "memory_recall",
+            "name": "cache_recall",
             "description": "Search past folder observations and global memories. Use when you need to recall what happened in a folder.",
             "inputSchema": {
                 "type": "object",
@@ -74,7 +75,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_smart_search",
+            "name": "cache_smart_search",
             "description": "Hybrid semantic+keyword search across folder observations and global memories.",
             "inputSchema": {
                 "type": "object",
@@ -88,7 +89,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_save",
+            "name": "cache_save",
             "description": "Explicitly save an important insight, decision, or pattern to long-term memory.",
             "inputSchema": {
                 "type": "object",
@@ -113,12 +114,12 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_diagnose",
+            "name": "cache_diagnose",
             "description": "Health check — returns folder, agent, observation and memory counts.",
             "inputSchema": {"type": "object", "properties": {}},
         },
         {
-            "name": "memory_forget",
+            "name": "cache_forget",
             "description": "Delete a global memory or all observations for a (folderPath, agentId) pair.",
             "inputSchema": {
                 "type": "object",
@@ -136,7 +137,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_export",
+            "name": "cache_export",
             "description": "Export all folder observations and global memories as JSON (v2 format).",
             "inputSchema": {"type": "object", "properties": {}},
         },
@@ -161,7 +162,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "agent_remember",
+            "name": "agent_cache",
             "description": "Explicitly save a key insight, fact, or architecture decision to long-term memory.",
             "inputSchema": {
                 "type": "object",
@@ -187,12 +188,12 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_folders",
+            "name": "cache_folders",
             "description": "List all (folder, agent) pairs that have memory observations.",
             "inputSchema": {"type": "object", "properties": {}},
         },
         {
-            "name": "memory_folder_observations",
+            "name": "cache_folder_observations",
             "description": "Get all observations for a specific (folderPath, agentId) pair.",
             "inputSchema": {
                 "type": "object",
@@ -204,7 +205,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_timeline",
+            "name": "cache_timeline",
             "description": "Get folder activity feed — observations sorted by time, filterable by folder/agent.",
             "inputSchema": {
                 "type": "object",
@@ -218,7 +219,7 @@ def mcp_tools_list():
             },
         },
         {
-            "name": "memory_dedup",
+            "name": "cache_dedup",
             "description": "Remove duplicate observations from a (folderPath, agentId) pair or all pairs. Keeps the earliest observation per unique text fingerprint.",
             "inputSchema": {
                 "type": "object",
@@ -233,9 +234,10 @@ def mcp_tools_list():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/mcp/tools
+# POST /agentcache/mcp/tools
 # ---------------------------------------------------------------------------
 
+@mcp_bp.route("/agentcache/mcp/tools", methods=["POST"])
 @mcp_bp.route("/agentmemory/mcp/tools", methods=["POST"])
 def mcp_tools_call():
     auth_err = _check_auth()
@@ -253,7 +255,7 @@ def mcp_tools_call():
         print(f"[mcp] Calling tool {name} with args: {args}")
         text_out = ""
 
-        if name == "memory_recall":
+        if name in ("cache_recall", "memory_recall"):
             q = args.get("query")
             limit = int(args.get("limit") or 10)
             folder_path = args.get("folderPath")
@@ -267,7 +269,7 @@ def mcp_tools_call():
             res = functions.folder_search(kv, q, limit, folder_path=folder_path, agent_id=agent_id)
             text_out = json.dumps(res, indent=2)
 
-        elif name == "memory_save":
+        elif name in ("cache_save", "memory_save"):
             content = args.get("content")
             concepts = _parse_mcp_list_arg(args.get("concepts"))
             files = _parse_mcp_list_arg(args.get("files"))
@@ -281,7 +283,7 @@ def mcp_tools_call():
             })
             text_out = json.dumps(res)
 
-        elif name == "memory_smart_search":
+        elif name in ("cache_smart_search", "memory_smart_search"):
             q = args.get("query")
             limit = int(args.get("limit") or 10)
             folder_path = args.get("folderPath")
@@ -295,11 +297,11 @@ def mcp_tools_call():
             res = functions.folder_search(kv, q, limit, folder_path=folder_path, agent_id=agent_id)
             text_out = json.dumps(res, indent=2)
 
-        elif name == "memory_diagnose":
+        elif name in ("cache_diagnose", "memory_diagnose"):
             res = functions.health_check(kv)
             text_out = json.dumps(res, indent=2)
 
-        elif name == "memory_forget":
+        elif name in ("cache_forget", "memory_forget"):
             obs_ids = _parse_mcp_list_arg(args.get("observationIds"))
             res = functions.forget(kv, {
                 "memoryId": args.get("memoryId"),
@@ -309,7 +311,7 @@ def mcp_tools_call():
             })
             text_out = json.dumps(res, indent=2)
 
-        elif name == "memory_export":
+        elif name in ("cache_export", "memory_export"):
             res = functions.export_data(kv, {})
             text_out = json.dumps(res, indent=2)
 
@@ -325,6 +327,7 @@ def mcp_tools_call():
                 folder_path = (
                     args.get("cwd")
                     or args.get("project")
+                    or os.getenv("AGENTCACHE_CWD")
                     or os.getenv("AGENTMEMORY_CWD")
                     or "/unknown"
                 )
@@ -361,7 +364,7 @@ def mcp_tools_call():
             res = functions.folder_observe(kv, payload)
             text_out = json.dumps(res)
 
-        elif name == "agent_remember":
+        elif name in ("agent_cache", "agent_remember"):
             agent_id = args.get("agentId") or functions.get_agent_id() or "agent"
             content = args.get("content")
             project = args.get("project")
@@ -389,7 +392,7 @@ def mcp_tools_call():
             res = functions.remember(kv, payload)
             text_out = json.dumps(res)
 
-        elif name == "memory_folders":
+        elif name in ("cache_folders", "memory_folders"):
             pairs = sorted(
                 kv.list(KV.folders),
                 key=lambda x: x.get("lastUpdated", ""),
@@ -401,7 +404,7 @@ def mcp_tools_call():
                     pairs = [p for p in pairs if p.get("agentId") == aid]
             text_out = json.dumps(pairs, indent=2)
 
-        elif name == "memory_folder_observations":
+        elif name in ("cache_folder_observations", "memory_folder_observations"):
             fp = args.get("folderPath", "")
             aid = args.get("agentId", "")
             if not fp or not aid:
@@ -417,7 +420,7 @@ def mcp_tools_call():
             )
             text_out = json.dumps(obs, indent=2)
 
-        elif name == "memory_timeline":
+        elif name in ("cache_timeline", "memory_timeline"):
             request_aid = args.get("agentId")
             if functions.is_agent_scope_isolated():
                 current_aid = functions.get_agent_id()
@@ -435,7 +438,7 @@ def mcp_tools_call():
             )
             text_out = json.dumps(res, indent=2)
 
-        elif name == "memory_dedup":
+        elif name in ("cache_dedup", "memory_dedup"):
             res = functions.dedup_folder_observations(
                 kv,
                 args.get("folderPath") or None,

src/routes/memories.py

@@ -18,7 +18,7 @@ memories_bp = Blueprint("memories", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -39,6 +39,7 @@ def _get_kv():
 # POST /agentmemory/remember
 # ---------------------------------------------------------------------------
 
+@memories_bp.route("/agentcache/remember", methods=["POST"])
 @memories_bp.route("/agentmemory/remember", methods=["POST"])
 def api_remember():
     auth_err = _check_auth()
@@ -57,6 +58,7 @@ def api_remember():
 # POST /agentmemory/agent/remember
 # ---------------------------------------------------------------------------
 
+@memories_bp.route("/agentcache/agent/remember", methods=["POST"])
 @memories_bp.route("/agentmemory/agent/remember", methods=["POST"])
 def api_agent_remember():
     auth_err = _check_auth()
@@ -101,6 +103,7 @@ def api_agent_remember():
 # GET /agentmemory/memories
 # ---------------------------------------------------------------------------
 
+@memories_bp.route("/agentcache/memories", methods=["GET"])
 @memories_bp.route("/agentmemory/memories", methods=["GET"])
 def api_memories_list():
     auth_err = _check_auth()
@@ -120,6 +123,7 @@ def api_memories_list():
 # POST /agentmemory/forget
 # ---------------------------------------------------------------------------
 
+@memories_bp.route("/agentcache/forget", methods=["POST"])
 @memories_bp.route("/agentmemory/forget", methods=["POST"])
 def api_forget():
     auth_err = _check_auth()

src/routes/migration.py

@@ -14,7 +14,7 @@ migration_bp = Blueprint("migration", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -32,9 +32,10 @@ def _get_kv():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/migrate
+# POST /agentcache/migrate
 # ---------------------------------------------------------------------------
 
+@migration_bp.route("/agentcache/migrate", methods=["POST"])
 @migration_bp.route("/agentmemory/migrate", methods=["POST"])
 def api_migrate():
     auth_err = _check_auth()

src/routes/observations.py

@@ -24,7 +24,7 @@ def _datetime_now_iso() -> str:
 def _check_auth():
     """Replicate the check_auth() pattern from app.py."""
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -46,6 +46,7 @@ def _get_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()
@@ -63,6 +64,7 @@ def api_observe():
             body.get("folderPath")
             or body.get("cwd")
             or body.get("project")
+            or os.getenv("AGENTCACHE_CWD")
             or os.getenv("AGENTMEMORY_CWD")
             or "/unknown"
         )
@@ -114,6 +116,7 @@ def api_observe():
 # POST /agentmemory/agent/observe
 # ---------------------------------------------------------------------------
 
+@observations_bp.route("/agentcache/agent/observe", methods=["POST"])
 @observations_bp.route("/agentmemory/agent/observe", methods=["POST"])
 def api_agent_observe():
     auth_err = _check_auth()
@@ -161,6 +164,7 @@ def api_agent_observe():
 # GET /agentmemory/folders
 # ---------------------------------------------------------------------------
 
+@observations_bp.route("/agentcache/folders", methods=["GET"])
 @observations_bp.route("/agentmemory/folders", methods=["GET"])
 def api_folders():
     auth_err = _check_auth()
@@ -182,6 +186,7 @@ def api_folders():
 # 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()
@@ -207,6 +212,7 @@ def api_folder_observations():
 # 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.
@@ -230,6 +236,7 @@ def api_session_start():
 # 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()
@@ -242,6 +249,7 @@ def api_session_end():
 # 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.
@@ -270,6 +278,7 @@ def api_folder_dedup():
 # 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.

src/routes/search.py

@@ -15,7 +15,7 @@ search_bp = Blueprint("search", __name__)
 
 def _check_auth():
     import hmac
-    secret = os.getenv("AGENTMEMORY_SECRET")
+    secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
     if not secret:
         return None
     auth = request.headers.get("Authorization") or request.headers.get("authorization")
@@ -33,9 +33,10 @@ def _get_kv():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/search
+# POST /agentcache/search
 # ---------------------------------------------------------------------------
 
+@search_bp.route("/agentcache/search", methods=["POST"])
 @search_bp.route("/agentmemory/search", methods=["POST"])
 def api_search():
     auth_err = _check_auth()
@@ -58,9 +59,10 @@ def api_search():
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/timeline
+# POST /agentcache/timeline
 # ---------------------------------------------------------------------------
 
+@search_bp.route("/agentcache/timeline", methods=["POST"])
 @search_bp.route("/agentmemory/timeline", methods=["POST"])
 def api_timeline():
     auth_err = _check_auth()

src/storage/scopes.py

@@ -2,7 +2,7 @@
 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 agentmemory-python.
+The KV class defines all storage scope keys used across agentcache-python.
 """
 
 

src/viewer/index.html

@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>agentmemory viewer</title>
+  <title>agentcache viewer</title>
   <link rel="icon" type="image/svg+xml" href="/favicon.svg">
   <!-- Removed Google Fonts <link> in #323: the viewer CSP is strict
        (default-src 'none', style-src 'unsafe-inline', font-src 'self')
@@ -1287,8 +1287,8 @@
 <body>
   <div class="app-header">
     <a class="brand" href="#folders" data-tab-link="folders" aria-label="Open folders view">
-      <h1>agentmemory</h1>
-      <span class="version">v__AGENTMEMORY_VERSION__</span>
+      <h1>agentcache</h1>
+      <span class="version">v__AGENTCACHE_VERSION__</span>
     </a>
     <div class="header-right">
       <span class="dateline" id="dateline"></span>
@@ -1329,7 +1329,7 @@
   </div>
 
   <footer id="viewer-footer" class="viewer-footer">
-    <span>agentmemory viewer &middot; <span id="footer-version">loading...</span></span>
+    <span>agentcache viewer &middot; <span id="footer-version">loading...</span></span>
     <span class="footer-sep">&middot;</span>
     <a href="https://github.com/rohitg00/agentmemory" target="_blank" rel="noopener">github</a>
     <span class="footer-sep">&middot;</span>
@@ -1338,7 +1338,7 @@
     <a id="footer-feedback" href="#" target="_blank" rel="noopener">report issue &rarr;</a>
   </footer>
 
-  <script nonce="__AGENTMEMORY_VIEWER_NONCE__">
+  <script nonce="__AGENTCACHE_VIEWER_NONCE__">
     var safeStorage = {
       _mem: {},
       getItem: function(key) {
@@ -1385,10 +1385,10 @@
       document.documentElement.dataset.theme = dark ? 'dark' : 'light';
       var btn = document.getElementById('theme-toggle');
       if (btn) btn.textContent = dark ? 'LIGHT' : 'DARK';
-      if (persist) safeStorage.setItem('agentmemory-theme', dark ? 'dark' : 'light');
+      if (persist) safeStorage.setItem('agentcache-theme', dark ? 'dark' : 'light');
     }
     window.toggleTheme = function() { applyTheme(!isDarkMode(), true); };
-    var savedTheme = safeStorage.getItem('agentmemory-theme');
+    var savedTheme = safeStorage.getItem('agentcache-theme');
     if (savedTheme) {
       applyTheme(savedTheme === 'dark', false);
     } else if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
@@ -1442,7 +1442,7 @@
     };
     var CB_STATE_COLORS = { closed: 'badge-green', open: 'badge-red', 'half-open': 'badge-yellow' };
     var TAB_IDS = ['folders', 'memories', 'graph', 'timeline', 'tools'];
-    var VIEWER_TOKEN_STORAGE_KEY = 'agentmemory-viewer-token';
+    var VIEWER_TOKEN_STORAGE_KEY = 'agentcache-viewer-token';
 
     var state = {
       activeTab: 'folders',
@@ -1539,8 +1539,8 @@
       }
     }
     (function() {
-      var autoToken = '__AGENTMEMORY_AUTO_TOKEN__';
-      if (autoToken && autoToken.length > 0 && autoToken !== '__AGENTMEMORY_AUTO_TOKEN__') {
+      var autoToken = '__AGENTCACHE_AUTO_TOKEN__';
+      if (autoToken && autoToken.length > 0 && autoToken !== '__AGENTCACHE_AUTO_TOKEN__') {
         try { sessionStorage.setItem(VIEWER_TOKEN_STORAGE_KEY, autoToken); } catch (_) {}
       }
     })();
@@ -1561,9 +1561,9 @@
         '<div class="viewer-auth-panel">' +
           '<div>' +
             '<div class="viewer-auth-title">Viewer authorization required</div>' +
-            '<div id="viewer-auth-desc" class="viewer-auth-desc">Enter <code>AGENTMEMORY_SECRET</code> to unlock viewer API access.</div>' +
+            '<div id="viewer-auth-desc" class="viewer-auth-desc">Enter <code>AGENTCACHE_SECRET</code> to unlock viewer API access.</div>' +
           '</div>' +
-          '<input id="viewer-auth-token" type="password" autocomplete="off" spellcheck="false" aria-label="AGENTMEMORY_SECRET" aria-describedby="viewer-auth-desc" placeholder="AGENTMEMORY_SECRET" />' +
+          '<input id="viewer-auth-token" type="password" autocomplete="off" spellcheck="false" aria-label="AGENTCACHE_SECRET" aria-describedby="viewer-auth-desc" placeholder="AGENTCACHE_SECRET" />' +
           '<button class="btn" data-action="save-viewer-token">Unlock</button>' +
         '</div>';
       var input = document.getElementById('viewer-auth-token');
@@ -1578,7 +1578,7 @@
 
     async function api(path, opts) {
       try {
-        var url = REST + '/agentmemory/' + path;
+        var url = REST + '/agentcache/' + path;
         var headers = Object.assign({ 'Cache-Control': 'no-cache' }, (opts && opts.headers) || {});
         var viewerToken = getViewerToken();
         if (viewerToken && !headers.Authorization && !headers.authorization) {
@@ -1673,7 +1673,7 @@
 
     async function loadDashboard() {
       // Dashboard tab was removed; redirect to the Folders tab which is the
-      // active landing page backed by real endpoints (/agentmemory/folders).
+      // active landing page backed by real endpoints (/agentcache/folders).
       switchTab('folders');
     }
 
@@ -1746,7 +1746,7 @@
       el.innerHTML = '<div style="padding:24px;"><div class="skeleton skeleton-card"></div><div class="skeleton skeleton-card"></div></div>';
       try {
         var qp = 'folderPath=' + encodeURIComponent(folderPath) + '&agentId=' + encodeURIComponent(agentId);
-        var result = await apiFetchRaw('/agentmemory/folder/observations?' + qp);
+        var result = await apiFetchRaw('/agentcache/folder/observations?' + qp);
         var obs = (result && result.observations) || [];
 
         var html = '<div id="folder-detail-root" style="padding:20px 24px;">';
@@ -1926,7 +1926,7 @@
       if (viewerToken && !headers.Authorization) headers['Authorization'] = 'Bearer ' + viewerToken;
       // Always use REST base so cross-origin ?port= param works correctly
       var url = path.startsWith('http') ? path
-        : REST + (path.startsWith('/') ? path : '/agentmemory/' + path);
+        : REST + (path.startsWith('/') ? path : '/agentcache/' + path);
       var res = await fetch(url, Object.assign({}, opts, { headers: headers }));
       if (!res.ok) throw new Error(res.status + ' ' + res.statusText);
       return res.json();
@@ -1955,7 +1955,7 @@
       state.graph.queryError = null;
       var graphData;
       try {
-        graphData = await apiFetchRaw('/agentmemory/graph');
+        graphData = await apiFetchRaw('/agentcache/graph');
       } catch(err) {
         state.graph.queryError = String(err);
         graphData = { nodes: [], edges: [] };
@@ -2715,7 +2715,7 @@
 
       var html = '<div class="card" style="margin-bottom:12px;padding:12px;background:var(--bg-subtle);">';
       html += '<div style="font-size:13px;color:var(--ink-muted);line-height:1.5;">';
-      html += '<strong>Memories</strong> are durable facts, architecture notes, conventions, and lessons saved via <code>memory_remember</code> MCP tool or the <code>/agentmemory/remember</code> endpoint. They survive across sessions and supersede each other as v1, v2, etc. ';
+      html += '<strong>Memories</strong> are durable facts, architecture notes, conventions, and lessons saved via <code>agent_cache</code> MCP tool or the <code>/agentcache/remember</code> endpoint. They survive across sessions and supersede each other as v1, v2, etc. ';
       html += '<span style="color:var(--ink-faint);">Shown: ' + items.length + ' total.</span>';
       html += '</div></div>';
 
@@ -2740,8 +2740,8 @@
         html += '<div class="empty-state">' +
           '<div class="empty-icon">&#128218;</div>' +
           '<div class="empty-title">No memories yet</div>' +
-          '<div class="empty-lead">Memories are the distilled facts agentmemory keeps across sessions &mdash; things like file paths, architectural decisions, and user preferences. Hooks capture them automatically during coding sessions; you can also save one directly.</div>' +
-          '<pre class="empty-cmd">memory_remember {\n  title: "auth uses jose middleware",\n  content: "src/middleware/auth.ts handles JWT validation",\n  type: "architecture"\n}</pre>' +
+          '<div class="empty-lead">Memories are the distilled facts agentcache keeps across sessions &mdash; things like file paths, architectural decisions, and user preferences. Hooks capture them automatically during coding sessions; you can also save one directly.</div>' +
+          '<pre class="empty-cmd">agent_cache {\n  title: "auth uses jose middleware",\n  content: "src/middleware/auth.ts handles JWT validation",\n  type: "architecture"\n}</pre>' +
           '<div><a class="empty-link" href="https://github.com/rohitg00/agentmemory#memories" target="_blank" rel="noopener">Memory types &rarr;</a></div>' +
           '</div>';
       } else {
@@ -2833,7 +2833,7 @@
         var body = { limit: 100 };
         if (folderPath) body.folderPath = folderPath;
         if (agentId) body.agentId = agentId;
-        var result = await apiFetchRaw('/agentmemory/timeline', {
+        var result = await apiFetchRaw('/agentcache/timeline', {
           method: 'POST',
           body: JSON.stringify(body)
         });
@@ -3114,11 +3114,11 @@
       renderObservations();
     }
 
-    // loadActivity removed — /agentmemory/sessions endpoint does not exist.
+    // loadActivity removed — /agentcache/sessions endpoint does not exist.
     async function loadActivity() { return; }
     function renderActivity() { return; }
 
-    // loadSessions removed — /agentmemory/sessions endpoint does not exist.
+    // loadSessions removed — /agentcache/sessions endpoint does not exist.
     async function loadSessions() { return; }
     function renderSessions() { return; }
     function selectSession(id) { return; }
@@ -3405,7 +3405,7 @@
           title: 'No LLM provider key set',
           keyLabel: 'ANTHROPIC_API_KEY',
           desc: 'Compression, summarization, and graph extraction stay disabled until a key is provided.',
-          enable: 'export ANTHROPIC_API_KEY=sk-ant-...\n# then restart: npx @agentmemory/agentmemory',
+          enable: 'export ANTHROPIC_API_KEY=sk-ant-...\n# then restart: npx @agentcache/agentcache',
           docs: 'https://github.com/rohitg00/agentmemory#quick-start',
           dismissKey: '__provider_noop',
         });
@@ -3478,7 +3478,7 @@
           '### Steps to reproduce\n\n' +
           '1. \n2. \n3. \n'
         );
-        fbEl.href = 'https://github.com/rohitg00/agentmemory/issues/new?title=' +
+        fbEl.href = 'https://github.com/rohitg00/agentcache/issues/new?title=' +
           encodeURIComponent('[viewer] ') + '&body=' + body;
       }
     }
@@ -3727,7 +3727,7 @@
     // B4 -- Onboarding card (empty state detection)
     // ==========================================================================
     function maybeShowOnboarding(health, flags) {
-      if (safeStorage.getItem('agentmemory_onboarding_dismissed')) return;
+      if (safeStorage.getItem('agentcache_onboarding_dismissed')) return;
       if ((health.observationCount || 0) > 0 || (health.memoryCount || 0) > 0) return;
       var el = document.getElementById('view-folders');
       if (!el) return;
@@ -3748,20 +3748,20 @@
           '</div></div>';
       }
 
-      var secretSet = false; // AGENTMEMORY_SECRET status not exposed by flags endpoint
+      var secretSet = false; // AGENTCACHE_SECRET status not exposed by flags endpoint
       var geminiSet = !!(flags && flags.embeddingProvider && flags.embeddingProvider !== 'none');
 
       var card = document.createElement('div');
       card.className = 'onboarding-card';
       card.innerHTML =
-        '<h2>Welcome to agentmemory</h2>' +
-        '<p>No observations yet. Complete these steps to start recording agent memory.</p>' +
-        step(1, secretSet, 'Set AGENTMEMORY_SECRET (optional auth)',
-          'echo "AGENTMEMORY_SECRET=your-secret-here" >> ~/.agentmemory/.env') +
+        '<h2>Welcome to agentcache</h2>' +
+        '<p>No observations yet. Complete these steps to start recording agent cache.</p>' +
+        step(1, secretSet, 'Set AGENTCACHE_SECRET (optional auth)',
+          'echo "AGENTCACHE_SECRET=your-secret-here" >> ~/.agentcache/.env') +
         step(2, geminiSet, 'Add GEMINI_API_KEY for semantic search',
-          'echo "GEMINI_API_KEY=your-key" >> ~/.agentmemory/.env') +
-        step(3, false, 'Point your agent at agentmemory',
-          'curl -X POST http://localhost:3111/agentmemory/agent/observe \\\n' +
+          'echo "GEMINI_API_KEY=your-key" >> ~/.agentcache/.env') +
+        step(3, false, 'Point your agent at agentcache',
+          'curl -X POST http://localhost:3111/agentcache/agent/observe \\\n' +
           '  -H "Content-Type: application/json" \\\n' +
           '  -d \'{"folderPath":"/your/project","agentId":"kiro","text":"Hello",' +
           '"timestamp":"' + new Date().toISOString() + '"}\'') +
@@ -3774,7 +3774,7 @@
         });
       });
       card.querySelector('.onboarding-dismiss').addEventListener('click', function() {
-        safeStorage.setItem('agentmemory_onboarding_dismissed', '1');
+        safeStorage.setItem('agentcache_onboarding_dismissed', '1');
         card.remove();
       });
 
@@ -3789,7 +3789,7 @@
         await _origLoadFolders.apply(this, arguments);
         // After load, check health for onboarding card
         try {
-          var h = await apiFetchRaw('/agentmemory/health');
+          var h = await apiFetchRaw('/agentcache/health');
           var f = state.flagsConfig;
           maybeShowOnboarding(h, f);
         } catch(_) {}
@@ -3812,7 +3812,7 @@
         '<div class="skeleton skeleton-card"></div>' +
         '</div>';
       try {
-        var data = await apiFetch('/agentmemory/mcp/tools');
+        var data = await apiFetch('/agentcache/mcp/tools');
         var tools = data.tools || [];
         renderToolsTab(el, tools);
       } catch(err) {
@@ -3890,7 +3890,7 @@
           var _toolToken = getViewerToken();
           var _toolHeaders = { 'Content-Type': 'application/json' };
           if (_toolToken) _toolHeaders['Authorization'] = 'Bearer ' + _toolToken;
-          var rawRes = await fetch(REST + '/agentmemory/mcp/tools', {
+          var rawRes = await fetch(REST + '/agentcache/mcp/tools', {
             method: 'POST',
             headers: _toolHeaders,
             body: JSON.stringify({ name: name, arguments: args })

src/viewer_helpers.py

@@ -23,14 +23,14 @@ def make_viewer_response(base_dir: str):
 
     nonce = base64.urlsafe_b64encode(secrets.token_bytes(16)).decode("utf-8").rstrip("=")
 
-    # D2.2: Never embed the raw AGENTMEMORY_SECRET in page source.
+    # D2.2: Never embed the raw AGENTCACHE_SECRET in page source.
     # Replace the placeholder with an empty string — the viewer authenticates
     # via the Authorization header set programmatically after load.
     html = (
         template
-        .replace("__AGENTMEMORY_VIEWER_NONCE__", nonce)
-        .replace("__AGENTMEMORY_VERSION__", "0.9.8")
-        .replace("__AGENTMEMORY_AUTO_TOKEN__", "")
+        .replace("__AGENTCACHE_VIEWER_NONCE__", nonce)
+        .replace("__AGENTCACHE_VERSION__", "0.9.8")
+        .replace("__AGENTCACHE_AUTO_TOKEN__", "")
     )
 
     csp = "; ".join([

src/workers.py

@@ -1,5 +1,5 @@
 """
-Background worker threads for agentmemory-python.
+Background worker threads for agentcache-python.
 
 Start all workers via start_background_workers(kv).
 Each worker runs as a daemon thread so it exits automatically when the process dies.

start.sh

@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 # Note: no set -e — sync failures must not kill the container
 
-# Create agentmemory data directories
-mkdir -p /home/user/.agentmemory
+# Create agentcache data directories
+mkdir -p /home/user/.agentcache
 
 # =============================================================================
 # Persistent storage via HF Dataset repo
 # Secrets to set in HF Space settings:
 #   HF_TOKEN              — write access to the dataset repo
 #   GEMINI_API_KEY        — powers graph, embeddings, compression, crystals
-#   AGENTMEMORY_DATASET_REPO — optional override (default: Yash030/agentmemory-python-data)
+#   AGENTCACHE_DATASET_REPO — optional override (default: Yash030/agentmemory-python-data)
 # =============================================================================
-export AGENTMEMORY_DATASET_REPO="${AGENTMEMORY_DATASET_REPO:-Yash030/agentmemory-python-data}"
+export AGENTCACHE_DATASET_REPO="${AGENTCACHE_DATASET_REPO:-${AGENTMEMORY_DATASET_REPO:-Yash030/agentmemory-python-data}}"
 
 echo "[start] Restoring data from HF Dataset..."
 python3 /app/sync.py restore
@@ -25,32 +25,32 @@ python3 /app/sync.py restore
 ) &
 
 # Generate HMAC secret on first boot, persist it so it survives dataset restore
-HMAC_FILE="/home/user/.agentmemory/.hmac"
+HMAC_FILE="/home/user/.agentcache/.hmac"
 if [ ! -s "$HMAC_FILE" ]; then
   SECRET="$(openssl rand -hex 32)"
   printf '%s\n' "$SECRET" > "$HMAC_FILE"
   chmod 600 "$HMAC_FILE"
   echo "================================================================"
-  echo "agentmemory: generated HMAC secret on first boot"
-  echo "AGENTMEMORY_SECRET=$SECRET"
-  echo "Copy this to your Space secrets as AGENTMEMORY_SECRET."
+  echo "agentcache: generated HMAC secret on first boot"
+  echo "AGENTCACHE_SECRET=$SECRET"
+  echo "Copy this to your Space secrets as AGENTCACHE_SECRET."
   echo "It will not be printed again."
   echo "================================================================"
 fi
-export AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat "$HMAC_FILE")}"
+export AGENTCACHE_SECRET="${AGENTCACHE_SECRET:-${AGENTMEMORY_SECRET:-$(cat "$HMAC_FILE")}}"
 
 # Write .env config for the daemon so it is loaded by src/app.py
-cat > /home/user/.agentmemory/.env <<EOF
+cat > /home/user/.agentcache/.env <<EOF
 GEMINI_API_KEY=${GEMINI_API_KEY}
-AGENTMEMORY_SECRET=${AGENTMEMORY_SECRET}
-AGENTMEMORY_URL=http://localhost:7860
+AGENTCACHE_SECRET=${AGENTCACHE_SECRET}
+AGENTCACHE_URL=http://localhost:7860
 III_ENGINE_URL=ws://localhost:49134
 GEMINI_MODEL=${GEMINI_MODEL:-gemini-2.5-flash}
 EMBEDDING_PROVIDER=gemini
 CONSOLIDATION_ENABLED=true
 GRAPH_EXTRACTION_ENABLED=true
-AGENTMEMORY_REFLECT=true
-AGENTMEMORY_AUTO_COMPRESS=true
+AGENTCACHE_REFLECT=true
+AGENTCACHE_AUTO_COMPRESS=true
 EOF
 
 # Set the port for Flask application to run on (Hugging Face Space expects 7860)
@@ -64,3 +64,4 @@ python3 src/app.py
 # Perform a final backup on shutdown
 echo "[start] Flask application exited. Performing final backup..."
 python3 /app/sync.py backup
+

sync.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Sync agentmemory data to/from a private HF Dataset repo.
+Sync agentcache data to/from a private HF Dataset repo.
 Usage:
   python3 sync.py restore   -- download DB from HF on startup
   python3 sync.py backup    -- upload DB to HF (called in loop)
@@ -24,13 +24,13 @@ except ImportError:
     sys.exit(0)
 
 HF_TOKEN = os.environ.get("HF_TOKEN", "")
-REPO_ID  = os.environ.get("AGENTMEMORY_DATASET_REPO", "Yash030/agentmemory-python-data")
-DATA_DIR = os.path.expanduser("~/.agentmemory")
-DB_PATH  = os.path.join(DATA_DIR, "agentmemory.db")
+REPO_ID  = os.environ.get("AGENTCACHE_DATASET_REPO") or os.environ.get("AGENTMEMORY_DATASET_REPO") or "Yash030/agentmemory-python-data"
+DATA_DIR = os.path.expanduser("~/.agentcache")
+DB_PATH  = os.path.join(DATA_DIR, "agentcache.db")
 
 # Only these paths are backed up/restored — everything else is ephemeral
 SYNC_FILES = [
-    "agentmemory.db",
+    "agentcache.db",
     ".hmac",
 ]
 SYNC_DIRS = [
@@ -232,7 +232,7 @@ def backup():
         return
 
     # Stage only the targeted files
-    staging = tempfile.mkdtemp(prefix="agentmemory_sync_")
+    staging = tempfile.mkdtemp(prefix="agentcache_sync_")
     try:
         for full, rel in targets:
             dest = os.path.join(staging, rel.replace("/", os.sep))

tests/test_api.py

@@ -21,6 +21,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 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 db import StateKV
@@ -31,6 +32,8 @@ def flask_app(tmp_path_factory):
 
     StateKV.__init__ = patched_init
     import 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
@@ -51,12 +54,12 @@ def _post(client, url, payload):
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/agent/observe
+# POST /agentcache/agent/observe
 # ---------------------------------------------------------------------------
 
 class TestAgentObserve:
     def test_valid_payload_returns_201(self, client):
-        resp = _post(client, "/agentmemory/agent/observe", {
+        resp = _post(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/test-project",
             "agentId": "kiro",
             "text": "Implemented new authentication middleware",
@@ -68,7 +71,7 @@ class TestAgentObserve:
         assert data["observationId"].startswith("fobs_")
 
     def test_missing_folder_path_returns_400(self, client):
-        resp = _post(client, "/agentmemory/agent/observe", {
+        resp = _post(client, "/agentcache/agent/observe", {
             "agentId": "kiro",
             "text": "Some work",
             "timestamp": _now(),
@@ -76,7 +79,7 @@ class TestAgentObserve:
         assert resp.status_code == 400
 
     def test_missing_agent_id_returns_400(self, client):
-        resp = _post(client, "/agentmemory/agent/observe", {
+        resp = _post(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/proj",
             "text": "Some work",
             "timestamp": _now(),
@@ -84,7 +87,7 @@ class TestAgentObserve:
         assert resp.status_code == 400
 
     def test_missing_text_returns_400(self, client):
-        resp = _post(client, "/agentmemory/agent/observe", {
+        resp = _post(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/proj",
             "agentId": "kiro",
             "timestamp": _now(),
@@ -93,46 +96,46 @@ class TestAgentObserve:
 
 
 # ---------------------------------------------------------------------------
-# POST /agentmemory/search
+# POST /agentcache/search
 # ---------------------------------------------------------------------------
 
 class TestSearch:
     def test_search_with_query_returns_200(self, client):
         # Seed data first
-        _post(client, "/agentmemory/agent/observe", {
+        _post(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/search-proj",
             "agentId": "kiro",
             "text": "Refactored the authentication system",
             "timestamp": _now(),
         })
-        resp = _post(client, "/agentmemory/search", {"query": "authentication"})
+        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, "/agentmemory/search", {})
+        resp = _post(client, "/agentcache/search", {})
         assert resp.status_code == 400
 
     def test_search_empty_query_returns_400(self, client):
-        resp = _post(client, "/agentmemory/search", {"query": "   "})
+        resp = _post(client, "/agentcache/search", {"query": "   "})
         assert resp.status_code == 400
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/folders
+# GET /agentcache/folders
 # ---------------------------------------------------------------------------
 
 class TestFolders:
     def test_get_folders_returns_200(self, client):
         # Ensure at least one folder exists from earlier tests
-        _post(client, "/agentmemory/agent/observe", {
+        _post(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/folders-check",
             "agentId": "kiro",
             "text": "Check folders endpoint",
             "timestamp": _now(),
         })
-        resp = client.get("/agentmemory/folders")
+        resp = client.get("/agentcache/folders")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "folders" in data
@@ -140,12 +143,12 @@ class TestFolders:
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/health
+# GET /agentcache/health
 # ---------------------------------------------------------------------------
 
 class TestHealth:
     def test_health_returns_200(self, client):
-        resp = client.get("/agentmemory/health")
+        resp = client.get("/agentcache/health")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "folderCount" in data
@@ -153,29 +156,29 @@ class TestHealth:
         assert "memoryCount" in data
 
     def test_health_status_ok(self, client):
-        resp = client.get("/agentmemory/health")
+        resp = client.get("/agentcache/health")
         data = resp.get_json()
         assert data.get("status") in ("ok", "degraded")
 
 
 # ---------------------------------------------------------------------------
-# GET /agentmemory/livez
+# GET /agentcache/livez
 # ---------------------------------------------------------------------------
 
 class TestLivez:
     def test_livez_returns_200_no_auth(self, client):
-        resp = client.get("/agentmemory/livez")
+        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["AGENTMEMORY_SECRET"] = "test-secret-123"
+        os.environ["AGENTCACHE_SECRET"] = "test-secret-123"
         try:
-            resp = client.get("/agentmemory/livez")
+            resp = client.get("/agentcache/livez")
             assert resp.status_code == 200
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
 
 # ---------------------------------------------------------------------------
@@ -184,35 +187,35 @@ class TestLivez:
 
 class TestAuthentication:
     def test_protected_endpoint_returns_401_with_wrong_token(self, client):
-        os.environ["AGENTMEMORY_SECRET"] = "correct-secret"
+        os.environ["AGENTCACHE_SECRET"] = "correct-secret"
         try:
             resp = client.get(
-                "/agentmemory/audit",
+                "/agentcache/audit",
                 headers={"Authorization": "Bearer wrong-token"},
             )
             assert resp.status_code == 401
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
     def test_protected_endpoint_passes_with_correct_token(self, client):
         secret = "my-test-secret-xyz"
-        os.environ["AGENTMEMORY_SECRET"] = secret
+        os.environ["AGENTCACHE_SECRET"] = secret
         try:
             resp = client.get(
-                "/agentmemory/audit",
+                "/agentcache/audit",
                 headers={"Authorization": f"Bearer {secret}"},
             )
             assert resp.status_code == 200
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
     def test_livez_always_open_regardless_of_secret(self, client):
-        os.environ["AGENTMEMORY_SECRET"] = "any-secret"
+        os.environ["AGENTCACHE_SECRET"] = "any-secret"
         try:
-            resp = client.get("/agentmemory/livez")
+            resp = client.get("/agentcache/livez")
             assert resp.status_code == 200
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
 
 # ---------------------------------------------------------------------------
@@ -221,34 +224,34 @@ class TestAuthentication:
 
 class TestMemoriesEndpoint:
     def test_memories_list_returns_200(self, client):
-        resp = client.get("/agentmemory/memories")
+        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, "/agentmemory/remember", {
+        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, "/agentmemory/forget", {"memoryId": "mem_nonexistent"})
+        resp = _post(client, "/agentcache/forget", {"memoryId": "mem_nonexistent"})
         assert resp.status_code == 200
 
     def test_graph_endpoint_returns_200(self, client):
-        resp = client.get("/agentmemory/graph")
+        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("/agentmemory/mcp/tools")
+        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 "memory_recall" in tool_names
+        assert "cache_recall" in tool_names

tests/test_context.py

@@ -18,7 +18,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 def _make_kv(tmp_path):
     from db import StateKV
-    os.environ.pop("AGENTMEMORY_SECRET", None)
+    os.environ.pop("AGENTCACHE_SECRET", None)
     return StateKV(db_path=str(tmp_path / "test.db"))
 
 
@@ -83,7 +83,7 @@ class TestContext:
         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 <agentmemory-context>."""
+        """Non-empty context should be wrapped in <agentcache-context>."""
         from functions import context, lesson_save
         kv = _make_kv(tmp_path)
         project = "/home/user/xml-test"
@@ -101,8 +101,8 @@ class TestContext:
         })
 
         if result["blocks"] > 0:
-            assert "<agentmemory-context" in result["context"]
-            assert "</agentmemory-context>" in result["context"]
+            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."""

tests/test_folder_observe.py

@@ -70,8 +70,8 @@ class TestFolderObserveSuccess:
 
     def test_obs_count_incremented(self, tmp_path):
         kv = make_kv(tmp_path)
-        folder_observe(kv, base_payload())
-        folder_observe(kv, base_payload())
+        folder_observe(kv, base_payload(text="First observation"))
+        folder_observe(kv, base_payload(text="Second observation"))
         fp = 'home/user/projects/myapp'
         meta = kv.get(KV.folder_meta(fp, 'kiro'), 'meta')
         assert meta is not None
@@ -99,10 +99,10 @@ class TestFolderObserveCap:
     def test_cap_enforced(self, tmp_path, monkeypatch):
         monkeypatch.setenv('MAX_OBS_PER_FOLDER', '3')
         kv = make_kv(tmp_path)
-        for _ in range(3):
-            folder_observe(kv, base_payload())
+        for i in range(3):
+            folder_observe(kv, base_payload(text=f"observation {i}"))
         with pytest.raises(ValueError, match='limit'):
-            folder_observe(kv, base_payload())
+            folder_observe(kv, base_payload(text="observation 4"))
 
 
 class TestFolderObservePairIsolation:

tests/test_properties.py

@@ -38,7 +38,7 @@ _counter = [0]
 def _fresh_kv():
     """Create a brand-new isolated StateKV in a temp directory."""
     from db import StateKV
-    os.environ.pop("AGENTMEMORY_SECRET", None)
+    os.environ.pop("AGENTCACHE_SECRET", None)
     _counter[0] += 1
     d = tempfile.mkdtemp(prefix=f"agmem_prop_{_counter[0]}_")
     return StateKV(db_path=os.path.join(d, "test.db"))

tests/test_remember.py

@@ -18,7 +18,7 @@ sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
 def _make_kv(tmp_path):
     from db import StateKV
-    os.environ.pop("AGENTMEMORY_SECRET", None)
+    os.environ.pop("AGENTCACHE_SECRET", None)
     return StateKV(db_path=str(tmp_path / "test.db"))
 
 

tests/test_route_regressions.py

@@ -6,7 +6,7 @@ the expected HTTP status codes after the monolithic app.py was split into
 src/routes/{observations, memories, search, graph, health, mcp, migration}.py.
 
 Tests use the Flask test client — no running server required.
-The AGENTMEMORY_SECRET env var is NOT set so all auth checks pass through.
+The AGENTCACHE_SECRET env var is NOT set so all auth checks pass through.
 """
 import sys
 import os
@@ -36,11 +36,14 @@ def flask_app(tmp_path_factory):
     db_path = str(tmp_dir / "test.db")
 
     # Point the server at an isolated DB
-    os.environ["AGENTMEMORY_DB_PATH"] = db_path
+    os.environ["AGENTCACHE_DB_PATH"] = db_path
     # Ensure no auth requirement during tests
+    os.environ.pop("AGENTCACHE_SECRET", None)
     os.environ.pop("AGENTMEMORY_SECRET", None)
 
     import app as app_module
+    os.environ.pop("AGENTCACHE_SECRET", None)
+    os.environ.pop("AGENTMEMORY_SECRET", None)
     from db import StateKV
 
     # Patch StateKV to use tmp db before create_app() initialises it
@@ -81,28 +84,28 @@ def _post_json(client, url, payload):
 
 # ===========================================================================
 # Blueprint 1: health.py
-#   GET /agentmemory/livez
-#   GET /agentmemory/health
-#   GET /agentmemory/audit
-#   GET /agentmemory/config/flags
+#   GET /agentcache/livez
+#   GET /agentcache/health
+#   GET /agentcache/audit
+#   GET /agentcache/config/flags
 # ===========================================================================
 
 class TestHealthBlueprint:
     def test_livez_no_auth_required(self, client):
         """GET /livez must respond 200 without any auth token (always open)."""
-        resp = client.get("/agentmemory/livez")
+        resp = client.get("/agentcache/livez")
         assert resp.status_code == 200
         data = resp.get_json()
         assert data["status"] == "ok"
         assert "service" in data
 
     def test_livez_returns_service_name(self, client):
-        resp = client.get("/agentmemory/livez")
+        resp = client.get("/agentcache/livez")
         data = resp.get_json()
-        assert data["service"] == "agentmemory"
+        assert data["service"] == "agentcache"
 
     def test_health_returns_200(self, client):
-        resp = client.get("/agentmemory/health")
+        resp = client.get("/agentcache/health")
         assert resp.status_code == 200
         data = resp.get_json()
         # Folder-based health check fields (REQ-047)
@@ -111,13 +114,13 @@ class TestHealthBlueprint:
         assert "memoryCount" in data
 
     def test_audit_returns_200(self, client):
-        resp = client.get("/agentmemory/audit")
+        resp = client.get("/agentcache/audit")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "entries" in data
 
     def test_config_flags_returns_200(self, client):
-        resp = client.get("/agentmemory/config/flags")
+        resp = client.get("/agentcache/config/flags")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "flags" in data
@@ -126,10 +129,10 @@ class TestHealthBlueprint:
 
 # ===========================================================================
 # Blueprint 2: observations.py
-#   POST /agentmemory/observe
-#   POST /agentmemory/agent/observe
-#   GET  /agentmemory/folders
-#   GET  /agentmemory/folder/observations
+#   POST /agentcache/observe
+#   POST /agentcache/agent/observe
+#   GET  /agentcache/folders
+#   GET  /agentcache/folder/observations
 # ===========================================================================
 
 class TestObservationsBlueprint:
@@ -141,7 +144,7 @@ class TestObservationsBlueprint:
             "text": "Added a new feature to the app",
             "timestamp": _now_iso(),
         }
-        resp = _post_json(client, "/agentmemory/agent/observe", payload)
+        resp = _post_json(client, "/agentcache/agent/observe", payload)
         assert resp.status_code == 201
         data = resp.get_json()
         assert "observationId" in data
@@ -150,31 +153,31 @@ class TestObservationsBlueprint:
     def test_agent_observe_missing_folder_path_returns_400(self, client):
         """POST /agent/observe missing folderPath returns 400."""
         payload = {"agentId": "kiro", "text": "some work", "timestamp": _now_iso()}
-        resp = _post_json(client, "/agentmemory/agent/observe", payload)
+        resp = _post_json(client, "/agentcache/agent/observe", payload)
         assert resp.status_code == 400
 
     def test_agent_observe_missing_agent_id_returns_400(self, client):
         """POST /agent/observe missing agentId returns 400."""
         payload = {"folderPath": "/home/user/proj", "text": "some work", "timestamp": _now_iso()}
-        resp = _post_json(client, "/agentmemory/agent/observe", payload)
+        resp = _post_json(client, "/agentcache/agent/observe", payload)
         assert resp.status_code == 400
 
     def test_agent_observe_missing_text_returns_400(self, client):
         """POST /agent/observe missing text returns 400."""
         payload = {"folderPath": "/home/user/proj", "agentId": "kiro", "timestamp": _now_iso()}
-        resp = _post_json(client, "/agentmemory/agent/observe", payload)
+        resp = _post_json(client, "/agentcache/agent/observe", payload)
         assert resp.status_code == 400
 
     def test_folders_list_returns_200(self, client):
         """GET /folders returns 200 with a folders list."""
         # Seed at least one observation first
-        _post_json(client, "/agentmemory/agent/observe", {
+        _post_json(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/proj-folders-test",
             "agentId": "kiro",
             "text": "Folders test observation",
             "timestamp": _now_iso(),
         })
-        resp = client.get("/agentmemory/folders")
+        resp = client.get("/agentcache/folders")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "folders" in data
@@ -184,20 +187,20 @@ class TestObservationsBlueprint:
         """GET /folder/observations with valid params returns 200."""
         # Seed an observation first
         fp = "/home/user/proj-obs-test"
-        _post_json(client, "/agentmemory/agent/observe", {
+        _post_json(client, "/agentcache/agent/observe", {
             "folderPath": fp,
             "agentId": "kiro",
             "text": "Obs for folder/observations test",
             "timestamp": _now_iso(),
         })
-        resp = client.get("/agentmemory/folder/observations?folderPath=home/user/proj-obs-test&agentId=kiro")
+        resp = client.get("/agentcache/folder/observations?folderPath=home/user/proj-obs-test&agentId=kiro")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "observations" in data
 
     def test_folder_observations_missing_params_returns_400(self, client):
         """GET /folder/observations without required params returns 400."""
-        resp = client.get("/agentmemory/folder/observations")
+        resp = client.get("/agentcache/folder/observations")
         assert resp.status_code == 400
 
     def test_legacy_observe_endpoint_returns_400_or_201(self, client):
@@ -208,17 +211,17 @@ class TestObservationsBlueprint:
             "text": "legacy observe call",
             "timestamp": _now_iso(),
         }
-        resp = _post_json(client, "/agentmemory/observe", payload)
+        resp = _post_json(client, "/agentcache/observe", payload)
         # The legacy endpoint exists — expect either success or a controlled error, never 404
         assert resp.status_code != 404
 
 
 # ===========================================================================
 # Blueprint 3: memories.py
-#   POST /agentmemory/remember
-#   POST /agentmemory/agent/remember
-#   GET  /agentmemory/memories
-#   POST /agentmemory/forget
+#   POST /agentcache/remember
+#   POST /agentcache/agent/remember
+#   GET  /agentcache/memories
+#   POST /agentcache/forget
 # ===========================================================================
 
 class TestMemoriesBlueprint:
@@ -229,12 +232,12 @@ class TestMemoriesBlueprint:
             "type": "fact",
             "concepts": ["sql", "security"],
         }
-        resp = _post_json(client, "/agentmemory/remember", payload)
+        resp = _post_json(client, "/agentcache/remember", payload)
         assert resp.status_code == 201
         data = resp.get_json()
         assert "memory" in data
 
-    def test_agent_remember_valid_payload(self, client):
+    def test_agent_cache_valid_payload(self, client):
         """POST /agent/remember with content returns 201."""
         payload = {
             "content": "The project uses SQLite with WAL mode",
@@ -242,17 +245,17 @@ class TestMemoriesBlueprint:
             "type": "architecture",
             "concepts": ["sqlite", "wal"],
         }
-        resp = _post_json(client, "/agentmemory/agent/remember", payload)
+        resp = _post_json(client, "/agentcache/agent/remember", payload)
         assert resp.status_code == 201
 
-    def test_agent_remember_missing_content_returns_400(self, client):
+    def test_agent_cache_missing_content_returns_400(self, client):
         """POST /agent/remember without content returns 400."""
-        resp = _post_json(client, "/agentmemory/agent/remember", {"agentId": "kiro"})
+        resp = _post_json(client, "/agentcache/agent/remember", {"agentId": "kiro"})
         assert resp.status_code == 400
 
     def test_memories_list_returns_200(self, client):
         """GET /memories returns 200 with memories list."""
-        resp = client.get("/agentmemory/memories")
+        resp = client.get("/agentcache/memories")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "memories" in data
@@ -260,7 +263,7 @@ class TestMemoriesBlueprint:
 
     def test_memories_list_latest_only(self, client):
         """GET /memories?latest=true filters to only latest memories."""
-        resp = client.get("/agentmemory/memories?latest=true")
+        resp = client.get("/agentcache/memories?latest=true")
         assert resp.status_code == 200
         data = resp.get_json()
         # All returned memories should be latest=True or isLatest not False
@@ -270,13 +273,13 @@ class TestMemoriesBlueprint:
     def test_forget_memory_by_id(self, client):
         """POST /forget with memoryId deletes a global memory."""
         # Create a memory first
-        create_resp = _post_json(client, "/agentmemory/remember", {
+        create_resp = _post_json(client, "/agentcache/remember", {
             "content": "This memory will be forgotten",
             "type": "fact",
         })
         mem_id = create_resp.get_json()["memory"]["id"]
         # Forget it
-        resp = _post_json(client, "/agentmemory/forget", {"memoryId": mem_id})
+        resp = _post_json(client, "/agentcache/forget", {"memoryId": mem_id})
         assert resp.status_code == 200
         data = resp.get_json()
         assert data["deleted"] >= 1
@@ -285,13 +288,13 @@ class TestMemoriesBlueprint:
         """POST /forget with folderPath+agentId clears folder observations."""
         # Seed an observation
         fp = "/home/user/proj-to-forget"
-        _post_json(client, "/agentmemory/agent/observe", {
+        _post_json(client, "/agentcache/agent/observe", {
             "folderPath": fp,
             "agentId": "kiro",
             "text": "Some work that will be forgotten",
             "timestamp": _now_iso(),
         })
-        resp = _post_json(client, "/agentmemory/forget", {
+        resp = _post_json(client, "/agentcache/forget", {
             "folderPath": fp,
             "agentId": "kiro",
         })
@@ -303,31 +306,31 @@ class TestMemoriesBlueprint:
 
 # ===========================================================================
 # Blueprint 4: search.py
-#   POST /agentmemory/search
-#   POST /agentmemory/timeline
+#   POST /agentcache/search
+#   POST /agentcache/timeline
 # ===========================================================================
 
 class TestSearchBlueprint:
     def test_search_with_query_returns_200(self, client):
         """POST /search with a query returns 200."""
         # Seed something searchable first
-        _post_json(client, "/agentmemory/agent/observe", {
+        _post_json(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/proj-search-test",
             "agentId": "kiro",
             "text": "Implemented authentication middleware for the app",
             "timestamp": _now_iso(),
         })
-        resp = _post_json(client, "/agentmemory/search", {"query": "authentication"})
+        resp = _post_json(client, "/agentcache/search", {"query": "authentication"})
         assert resp.status_code == 200
 
     def test_search_missing_query_returns_400(self, client):
         """POST /search without query returns 400."""
-        resp = _post_json(client, "/agentmemory/search", {})
+        resp = _post_json(client, "/agentcache/search", {})
         assert resp.status_code == 400
 
     def test_search_with_folder_filter(self, client):
         """POST /search with folderPath filter returns 200."""
-        resp = _post_json(client, "/agentmemory/search", {
+        resp = _post_json(client, "/agentcache/search", {
             "query": "test",
             "folderPath": "/home/user/proj-search-test",
             "agentId": "kiro",
@@ -336,7 +339,7 @@ class TestSearchBlueprint:
 
     def test_timeline_returns_200(self, client):
         """POST /timeline returns 200 with observations list."""
-        resp = _post_json(client, "/agentmemory/timeline", {})
+        resp = _post_json(client, "/agentcache/timeline", {})
         assert resp.status_code == 200
         data = resp.get_json()
         assert "observations" in data
@@ -344,7 +347,7 @@ class TestSearchBlueprint:
 
     def test_timeline_with_filters_returns_200(self, client):
         """POST /timeline with folder/agent filters returns 200."""
-        resp = _post_json(client, "/agentmemory/timeline", {
+        resp = _post_json(client, "/agentcache/timeline", {
             "folderPath": "/home/user/proj-search-test",
             "agentId": "kiro",
             "limit": 10,
@@ -357,11 +360,11 @@ class TestSearchBlueprint:
         # Seed observations with distinct timestamps
         for i in range(3):
             ts = datetime.datetime(2025, 6, 1, 10, i, 0).isoformat() + "Z"
-            _post_json(client, "/agentmemory/agent/observe", {
+            _post_json(client, "/agentcache/agent/observe", {
                 "folderPath": fp, "agentId": "kiro",
                 "text": f"Observation {i}", "timestamp": ts,
             })
-        resp = _post_json(client, "/agentmemory/timeline", {
+        resp = _post_json(client, "/agentcache/timeline", {
             "folderPath": fp, "agentId": "kiro",
         })
         assert resp.status_code == 200
@@ -372,16 +375,16 @@ class TestSearchBlueprint:
 
 # ===========================================================================
 # Blueprint 5: graph.py
-#   GET  /agentmemory/graph
-#   GET  /agentmemory/graph/stats
-#   POST /agentmemory/graph/query
-#   POST /agentmemory/graph/build
+#   GET  /agentcache/graph
+#   GET  /agentcache/graph/stats
+#   POST /agentcache/graph/query
+#   POST /agentcache/graph/build
 # ===========================================================================
 
 class TestGraphBlueprint:
     def test_graph_returns_200(self, client):
         """GET /graph returns 200 with nodes and edges."""
-        resp = client.get("/agentmemory/graph")
+        resp = client.get("/agentcache/graph")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "nodes" in data
@@ -389,7 +392,7 @@ class TestGraphBlueprint:
 
     def test_graph_stats_returns_200(self, client):
         """GET /graph/stats returns 200."""
-        resp = client.get("/agentmemory/graph/stats")
+        resp = client.get("/agentcache/graph/stats")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "nodes" in data
@@ -397,24 +400,24 @@ class TestGraphBlueprint:
 
     def test_graph_query_returns_200(self, client):
         """POST /graph/query returns 200."""
-        resp = _post_json(client, "/agentmemory/graph/query", {})
+        resp = _post_json(client, "/agentcache/graph/query", {})
         assert resp.status_code == 200
 
     def test_graph_build_returns_200(self, client):
         """POST /graph/build returns 200."""
-        resp = _post_json(client, "/agentmemory/graph/build", {})
+        resp = _post_json(client, "/agentcache/graph/build", {})
         assert resp.status_code == 200
 
     def test_graph_nodes_have_required_fields(self, client):
         """Graph nodes contain id, label, folderPath, agentIds, obsCount, color (REQ-024)."""
         # Seed some data
-        _post_json(client, "/agentmemory/agent/observe", {
+        _post_json(client, "/agentcache/agent/observe", {
             "folderPath": "/home/user/proj-graph-check",
             "agentId": "kiro",
             "text": "Graph node field check",
             "timestamp": _now_iso(),
         })
-        resp = client.get("/agentmemory/graph")
+        resp = client.get("/agentcache/graph")
         data = resp.get_json()
         if data["nodes"]:
             node = data["nodes"][0]
@@ -424,14 +427,14 @@ class TestGraphBlueprint:
 
 # ===========================================================================
 # Blueprint 6: mcp.py
-#   GET  /agentmemory/mcp/tools
-#   POST /agentmemory/mcp/tools
+#   GET  /agentcache/mcp/tools
+#   POST /agentcache/mcp/tools
 # ===========================================================================
 
 class TestMcpBlueprint:
     def test_mcp_tools_list_returns_200(self, client):
         """GET /mcp/tools returns 200 with a tools list."""
-        resp = client.get("/agentmemory/mcp/tools")
+        resp = client.get("/agentcache/mcp/tools")
         assert resp.status_code == 200
         data = resp.get_json()
         assert "tools" in data
@@ -440,20 +443,20 @@ class TestMcpBlueprint:
 
     def test_mcp_tools_contains_required_tools(self, client):
         """The expected MCP tools are all present in the schema."""
-        resp = client.get("/agentmemory/mcp/tools")
+        resp = client.get("/agentcache/mcp/tools")
         tool_names = {t["name"] for t in resp.get_json()["tools"]}
         required_tools = {
             "agent_observe",
-            "memory_recall",
-            "memory_save",
-            "agent_remember",
-            "memory_diagnose",
-            "memory_forget",
-            "memory_export",
-            "memory_smart_search",
-            "memory_folders",
-            "memory_folder_observations",
-            "memory_timeline",
+            "cache_recall",
+            "cache_save",
+            "agent_cache",
+            "cache_diagnose",
+            "cache_forget",
+            "cache_export",
+            "cache_smart_search",
+            "cache_folders",
+            "cache_folder_observations",
+            "cache_timeline",
         }
         assert required_tools.issubset(tool_names), \
             f"Missing tools: {required_tools - tool_names}"
@@ -469,23 +472,23 @@ class TestMcpBlueprint:
                 "timestamp": _now_iso(),
             },
         }
-        resp = _post_json(client, "/agentmemory/mcp/tools", payload)
+        resp = _post_json(client, "/agentcache/mcp/tools", payload)
         assert resp.status_code == 200
         data = resp.get_json()
         assert "content" in data
 
-    def test_mcp_tool_call_memory_recall(self, client):
-        """POST /mcp/tools memory_recall returns 200."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {
-            "name": "memory_recall",
+    def test_mcp_tool_call_cache_recall(self, client):
+        """POST /mcp/tools cache_recall returns 200."""
+        resp = _post_json(client, "/agentcache/mcp/tools", {
+            "name": "cache_recall",
             "arguments": {"query": "authentication"},
         })
         assert resp.status_code == 200
 
-    def test_mcp_tool_call_memory_diagnose(self, client):
-        """POST /mcp/tools memory_diagnose returns folderCount etc."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {
-            "name": "memory_diagnose",
+    def test_mcp_tool_call_cache_diagnose(self, client):
+        """POST /mcp/tools cache_diagnose returns folderCount etc."""
+        resp = _post_json(client, "/agentcache/mcp/tools", {
+            "name": "cache_diagnose",
             "arguments": {},
         })
         assert resp.status_code == 200
@@ -494,25 +497,25 @@ class TestMcpBlueprint:
         assert "folderCount" in result
         assert "observationCount" in result
 
-    def test_mcp_tool_call_memory_folders(self, client):
-        """POST /mcp/tools memory_folders returns list."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {
-            "name": "memory_folders",
+    def test_mcp_tool_call_cache_folders(self, client):
+        """POST /mcp/tools cache_folders returns list."""
+        resp = _post_json(client, "/agentcache/mcp/tools", {
+            "name": "cache_folders",
             "arguments": {},
         })
         assert resp.status_code == 200
 
-    def test_mcp_tool_call_memory_timeline(self, client):
-        """POST /mcp/tools memory_timeline returns list."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {
-            "name": "memory_timeline",
+    def test_mcp_tool_call_cache_timeline(self, client):
+        """POST /mcp/tools cache_timeline returns list."""
+        resp = _post_json(client, "/agentcache/mcp/tools", {
+            "name": "cache_timeline",
             "arguments": {"limit": 10},
         })
         assert resp.status_code == 200
 
     def test_mcp_tool_unknown_name_returns_400(self, client):
         """POST /mcp/tools with unknown tool name returns 400."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {
+        resp = _post_json(client, "/agentcache/mcp/tools", {
             "name": "nonexistent_tool_xyz",
             "arguments": {},
         })
@@ -520,19 +523,19 @@ class TestMcpBlueprint:
 
     def test_mcp_tool_missing_name_returns_400(self, client):
         """POST /mcp/tools without name returns 400."""
-        resp = _post_json(client, "/agentmemory/mcp/tools", {"arguments": {}})
+        resp = _post_json(client, "/agentcache/mcp/tools", {"arguments": {}})
         assert resp.status_code == 400
 
 
 # ===========================================================================
 # Blueprint 7: migration.py
-#   POST /agentmemory/migrate
+#   POST /agentcache/migrate
 # ===========================================================================
 
 class TestMigrationBlueprint:
     def test_migrate_dry_run_returns_200(self, client):
         """POST /migrate with dry_run=true returns 200 with counts."""
-        resp = _post_json(client, "/agentmemory/migrate", {"dry_run": True})
+        resp = _post_json(client, "/agentcache/migrate", {"dry_run": True})
         assert resp.status_code == 200
         data = resp.get_json()
         assert "migrated_sessions" in data
@@ -541,7 +544,7 @@ class TestMigrationBlueprint:
 
     def test_migrate_without_body_defaults_to_no_dry_run(self, client):
         """POST /migrate with empty body returns 200."""
-        resp = _post_json(client, "/agentmemory/migrate", {})
+        resp = _post_json(client, "/agentcache/migrate", {})
         assert resp.status_code == 200
 
 
@@ -555,48 +558,48 @@ class TestBlueprintRegistration:
         registered_rules = {rule.rule for rule in flask_app.url_map.iter_rules()}
 
         # observations.py
-        assert "/agentmemory/agent/observe" in registered_rules
-        assert "/agentmemory/folders" in registered_rules
-        assert "/agentmemory/folder/observations" in registered_rules
+        assert "/agentcache/agent/observe" in registered_rules
+        assert "/agentcache/folders" in registered_rules
+        assert "/agentcache/folder/observations" in registered_rules
 
         # memories.py
-        assert "/agentmemory/remember" in registered_rules
-        assert "/agentmemory/memories" in registered_rules
-        assert "/agentmemory/forget" in registered_rules
+        assert "/agentcache/remember" in registered_rules
+        assert "/agentcache/memories" in registered_rules
+        assert "/agentcache/forget" in registered_rules
 
         # search.py
-        assert "/agentmemory/search" in registered_rules
-        assert "/agentmemory/timeline" in registered_rules
+        assert "/agentcache/search" in registered_rules
+        assert "/agentcache/timeline" in registered_rules
 
         # graph.py
-        assert "/agentmemory/graph" in registered_rules
-        assert "/agentmemory/graph/stats" in registered_rules
-        assert "/agentmemory/graph/query" in registered_rules
+        assert "/agentcache/graph" in registered_rules
+        assert "/agentcache/graph/stats" in registered_rules
+        assert "/agentcache/graph/query" in registered_rules
 
         # health.py
-        assert "/agentmemory/livez" in registered_rules
-        assert "/agentmemory/health" in registered_rules
-        assert "/agentmemory/audit" in registered_rules
-        assert "/agentmemory/config/flags" in registered_rules
+        assert "/agentcache/livez" in registered_rules
+        assert "/agentcache/health" in registered_rules
+        assert "/agentcache/audit" in registered_rules
+        assert "/agentcache/config/flags" in registered_rules
 
         # mcp.py
-        assert "/agentmemory/mcp/tools" in registered_rules
+        assert "/agentcache/mcp/tools" in registered_rules
 
         # migration.py
-        assert "/agentmemory/migrate" in registered_rules
+        assert "/agentcache/migrate" in registered_rules
 
     def test_no_routes_return_404_from_blueprints(self, client):
         """None of the expected blueprint routes return 404."""
         get_routes = [
-            "/agentmemory/livez",
-            "/agentmemory/health",
-            "/agentmemory/folders",
-            "/agentmemory/memories",
-            "/agentmemory/graph",
-            "/agentmemory/graph/stats",
-            "/agentmemory/audit",
-            "/agentmemory/config/flags",
-            "/agentmemory/mcp/tools",
+            "/agentcache/livez",
+            "/agentcache/health",
+            "/agentcache/folders",
+            "/agentcache/memories",
+            "/agentcache/graph",
+            "/agentcache/graph/stats",
+            "/agentcache/audit",
+            "/agentcache/config/flags",
+            "/agentcache/mcp/tools",
         ]
         for route in get_routes:
             resp = client.get(route)
@@ -605,7 +608,7 @@ class TestBlueprintRegistration:
     def test_cors_headers_present_on_responses(self, client):
         """CORS after_request hook adds the expected headers."""
         resp = client.get(
-            "/agentmemory/livez",
+            "/agentcache/livez",
             headers={"Origin": "http://localhost:3000"},
         )
         assert resp.status_code == 200
@@ -614,35 +617,35 @@ class TestBlueprintRegistration:
         assert "Access-Control-Allow-Methods" in resp.headers
 
     def test_auth_returns_401_when_secret_set(self, client, flask_app):
-        """When AGENTMEMORY_SECRET is configured, missing token returns 401 on protected routes.
+        """When AGENTCACHE_SECRET is configured, missing token returns 401 on protected routes.
 
-        /agentmemory/audit requires auth; /agentmemory/livez and /agentmemory/health are open.
+        /agentcache/audit requires auth; /agentcache/livez and /agentcache/health are open.
         """
-        os.environ["AGENTMEMORY_SECRET"] = "test-secret-token"
+        os.environ["AGENTCACHE_SECRET"] = "test-secret-token"
         try:
-            resp = client.get("/agentmemory/audit")
+            resp = client.get("/agentcache/audit")
             assert resp.status_code == 401
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
     def test_auth_passes_with_correct_bearer_token(self, client, flask_app):
         """Correct Bearer token passes auth on protected endpoints."""
         secret = "test-secret-token-correct"
-        os.environ["AGENTMEMORY_SECRET"] = secret
+        os.environ["AGENTCACHE_SECRET"] = secret
         try:
             resp = client.get(
-                "/agentmemory/audit",
+                "/agentcache/audit",
                 headers={"Authorization": f"Bearer {secret}"},
             )
             assert resp.status_code == 200
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]
 
     def test_livez_always_open_regardless_of_secret(self, client):
         """GET /livez is always unauthenticated, even when secret is set (REQ-057)."""
-        os.environ["AGENTMEMORY_SECRET"] = "some-secret"
+        os.environ["AGENTCACHE_SECRET"] = "some-secret"
         try:
-            resp = client.get("/agentmemory/livez")
+            resp = client.get("/agentcache/livez")
             assert resp.status_code == 200
         finally:
-            del os.environ["AGENTMEMORY_SECRET"]
+            del os.environ["AGENTCACHE_SECRET"]

tests/test_timeline.py

@@ -48,14 +48,14 @@ class TestTimelineLimit:
     def test_limit_respected(self, tmp_path):
         kv = make_kv(tmp_path)
         for i in range(10):
-            add_obs(kv, timestamp=ts(i))
+            add_obs(kv, timestamp=ts(i), text=f"obs {i}")
         results = folder_timeline(kv, limit=5)
         assert len(results) == 5
 
     def test_default_limit_100(self, tmp_path):
         kv = make_kv(tmp_path)
         for i in range(150):
-            add_obs(kv, timestamp=ts(i))
+            add_obs(kv, timestamp=ts(i), text=f"obs {i}")
         results = folder_timeline(kv)
         assert len(results) == 100