refactor: folder-based memory model replacing session-based storage

- Replace session-based KV scopes with (folder_path, agent_id) pairs
- Add normalize_folder_path, folder_observe, folder_search, folder_timeline, folder_graph_build
- Update forget/health_check/export_data/rebuild_index for folder model
- Add migrate_sessions_to_folders (non-destructive migration)
- Rewrite REST layer: /folders, /folder/observations, /timeline, /graph, /migrate
- Trim MCP tools from 31 to 11; add memory_folders, memory_folder_observations, memory_timeline
- Rebuild viewer to 4 tabs: Folders, Memories, Graph, Timeline
- Add pytest test suite: test_normalize, test_folder_observe, test_forget, test_timeline, test_graph, test_migration
- Add pytest==8.3.5 and hypothesis==6.131.15 to requirements.txt

.kiro/specs/folder-based-memory/.config.kiro

@@ -0,0 +1 @@
+{"specId": "44d10716-f6a0-45b2-9627-5d567a5ef29f", "workflowType": "design-first", "specType": "feature"}

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

@@ -0,0 +1,1026 @@
+# Design Document: Folder-Based Memory
+
+## Overview
+
+This document describes the complete restructure of agentmemory-python from a **session-based** architecture to a **folder-based memory** model. The primary unit of storage shifts from `(session_id)` to `(folder_path, agent_id)` — each agent accumulates observations scoped to the folder it is working in, with no concept of "sessions". Long-term memories remain global. The viewer, MCP tools, and REST API are all reshaped around this model.
+
+The redesign eliminates sessions, lessons, slots, actions, crystals, and artefacts entirely. What remains is: folder observations, global memories, BM25 + optional vector search, a folder-based graph, a folder activity feed (timeline), privacy stripping, and the MCP tool-calling interface.
+
+---
+
+## Architecture
+
+### High-Level System Diagram
+
+```mermaid
+graph TD
+    subgraph Agents
+        A1[Kiro]
+        A2[Claude]
+        A3[Cursor]
+    end
+
+    subgraph MCP / REST API ["MCP / REST API (src/app.py)"]
+        T1[agent_observe]
+        T2[memory_recall]
+        T3[memory_save / agent_remember]
+        T4[memory_smart_search]
+        T5[memory_export]
+        T6[memory_forget]
+        T7[memory_diagnose]
+    end
+
+    subgraph Business Logic ["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]
+        F7[strip_private_data]
+        F8[IndexPersistence]
+    end
+
+    subgraph Storage ["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]
+    end
+
+    subgraph Search ["Search (src/search.py)"]
+        SR1[SearchIndex BM25]
+        SR2[VectorIndex cosine]
+        SR3[HybridSearch RRF]
+    end
+
+    subgraph Viewer ["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
+    T1 --> F1
+    T2 & T4 --> F2
+    T3 --> F3
+    T5 --> F6
+    T6 --> F3
+    T7 --> F6
+
+    F1 --> F7
+    F1 --> S2
+    F1 --> SR1 & SR2
+    F1 --> S1
+    F3 --> S3
+    F2 --> SR3
+    SR1 & SR2 --> SR3
+    F8 --> S4
+    SR1 & SR2 --> F8
+
+    F4 --> S2
+    F5 --> S1 & S2 & S3
+
+    S2 & S3 & S4 & S5 --> Storage
+
+    Viewer --> T2 & T4
+    F1 -.->|WebSocket broadcast| Viewer
+```
+
+---
+
+## Sequence Diagrams
+
+### agent_observe — Folder Observation Pipeline
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant REST as REST /agent/observe
+    participant Fn as functions.folder_observe()
+    participant Privacy as strip_private_data()
+    participant KV as StateKV (SQLite)
+    participant BM25 as SearchIndex
+    participant Vec as VectorIndex
+    participant WS as WebSocket broadcast
+
+    Agent->>REST: POST /agentmemory/agent/observe\n{agentId, folderPath, text, type, title}
+    REST->>Fn: folder_observe(kv, payload)
+    Fn->>Privacy: strip_private_data(text)
+    Privacy-->>Fn: sanitized_text
+    Fn->>KV: set(KV.folder_obs(folder_path, agent_id), obs_id, obs)
+    Fn->>KV: upsert(KV.folder_meta(folder_path, agent_id), metadata)
+    Fn->>KV: ensure folder_path in KV.folders index
+    Fn->>BM25: add(obs)
+    Fn->>Vec: add(obs_id, embedding) [if provider set]
+    Fn->>KV: audit_log entry
+    Fn->>WS: broadcast compressed_observation
+    Fn-->>REST: {observationId}
+    REST-->>Agent: 201 {observationId}
+```
+
+### memory_recall — Hybrid Search
+
+```mermaid
+sequenceDiagram
+    participant Agent
+    participant REST as REST /search
+    participant Fn as functions.folder_search()
+    participant BM25 as SearchIndex
+    participant Vec as VectorIndex
+    participant RRF as HybridSearch
+    participant KV as StateKV
+
+    Agent->>REST: POST /agentmemory/search\n{query, limit, agentId?, folderPath?}
+    REST->>Fn: folder_search(kv, query, opts)
+    Fn->>BM25: search(query, limit*2)
+    BM25-->>Fn: [{obsId, score}]
+    Fn->>Vec: search(embedding, limit*2) [if available]
+    Vec-->>Fn: [{obsId, score}]
+    Fn->>RRF: fuse(bm25_results, vector_results)
+    RRF-->>Fn: [{obsId, combinedScore}]
+    Fn->>KV: hydrate each obsId → full observation
+    Fn-->>REST: [{observation, score, folderPath, agentId}]
+    REST-->>Agent: 200 [{...}]
+```
+
+---
+
+## Components and Interfaces
+
+### Component 1: KV Scope Registry (src/functions.py — `KV` class)
+
+**Purpose**: Single source of truth for all KV scope names.
+
+**New scopes (replaces session-based scopes):**
+
+```python
+class KV:
+    # Folder memory index — stores list of all known folder_paths
+    folders = "mem:folders"
+
+    # Per-(folder, agent) observations list
+    # key = obs_id, value = observation dict
+    @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)
+    @staticmethod
+    def folder_meta(folder_path: str, agent_id: str) -> str:
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:foldermeta:{safe_path}:{safe_agent}"
+
+    # Global long-term memories (unchanged)
+    memories = "mem:memories"
+
+    # BM25 index shards (unchanged)
+    bm25Index = "mem:index:bm25"
+
+    # Audit scope (unchanged)
+    audit = "mem:audit"
+```
+
+**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`
+
+**Scopes kept**: `memories`, `index:bm25:*`, `audit`, `relations` (repurposed for folder graph edges)
+
+---
+
+### Component 2: FolderMemory — Core Data Model
+
+**Purpose**: Represents a single `(folder_path, agent_id)` memory slice.
+
+```python
+# Observation stored under KV.folder_obs(folder_path, agent_id)
+FolderObservation = {
+    "id": str,            # generate_id("fobs")
+    "folderPath": str,    # normalized absolute path, forward-slashes
+    "agentId": str,       # e.g. "kiro", "claude", "cursor"
+    "timestamp": str,     # ISO 8601 UTC
+    "text": str,          # sanitized observation text (private data stripped)
+    "type": str,          # "file_edit" | "command_run" | "search" | "conversation" | "other" ...
+    "title": str,         # short summary ≤ 80 chars
+    "concepts": list[str],# extracted concept tags
+    "files": list[str],   # file paths referenced in this observation
+    "importance": int,    # 1-10, default 5
+}
+
+# Metadata stored under KV.folder_meta(folder_path, agent_id)
+FolderMeta = {
+    "folderPath": str,
+    "agentId": str,
+    "lastUpdated": str,   # ISO timestamp of most recent observation
+    "obsCount": int,
+    "summary": str | None, # optional LLM-generated or auto-compressed summary
+}
+
+# Entry in the global folders index (KV.folders, key = "{folder_path}:{agent_id}")
+FolderIndexEntry = {
+    "folderPath": str,
+    "agentId": str,
+    "lastUpdated": str,
+    "obsCount": int,
+}
+```
+
+---
+
+### Component 3: `folder_observe()` — Observation Ingestion
+
+**Purpose**: Replace `observe()`. Accept a folder path + agent ID instead of session ID.
+
+**Interface**:
+
+```python
+def folder_observe(kv: StateKV, payload: dict) -> dict:
+    """
+    Required payload fields:
+        folderPath: str      — absolute path of working directory
+        agentId: str         — identity of the agent making the observation
+        text: str            — human-readable observation content
+        timestamp: str       — ISO 8601 UTC
+
+    Optional payload fields:
+        type: str            — observation type (default "other")
+        title: str           — short title (auto-generated from text if absent)
+        concepts: list[str]  — tags
+        files: list[str]     — referenced file paths
+        importance: int      — 1-10 (default 5)
+
+    Returns: {"observationId": str}
+    Raises:  ValueError if required fields are missing or folder cap exceeded.
+    """
+```
+
+**Responsibilities**:
+- Validate `folderPath`, `agentId`, `text`, `timestamp`
+- Call `strip_private_data(text)` before any storage
+- Normalize `folderPath`: `os.path.normpath`, convert separators to `/`
+- Generate `obs_id = generate_id("fobs")`
+- Build observation dict, cap text at 4000 chars (same spirit as current `MAX_OBS_PER_SESSION`)
+- Write to `KV.folder_obs(folder_path, agent_id)` under key `obs_id`
+- Upsert `KV.folder_meta(folder_path, agent_id)`: increment `obsCount`, update `lastUpdated`
+- Upsert `KV.folders` index entry (key = `"{folder_path}:{agent_id}"`)
+- Add to BM25 index (`_bm25_index.add(obs)`)
+- Add to vector index if provider available
+- Schedule index persistence save
+- Write audit log entry
+- Broadcast to WebSocket viewers
+
+---
+
+### Component 4: `folder_search()` — Hybrid Search
+
+**Purpose**: Search across all folder observations (and memories) using the existing BM25+vector pipeline.
+
+```python
+def folder_search(
+    kv: StateKV,
+    query: str,
+    limit: int = 20,
+    folder_path: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> list[dict]:
+    """
+    Returns hydrated observations sorted by relevance.
+    Optionally filtered to a specific folder or agent.
+    Combines BM25 + vector via RRF (existing HybridSearch).
+    Also includes matching global memories in results.
+    """
+```
+
+---
+
+### Component 5: `folder_timeline()` — Activity Feed
+
+**Purpose**: Replace session-based timeline with a folder activity feed.
+
+```python
+def folder_timeline(
+    kv: StateKV,
+    limit: int = 100,
+    folder_path: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    before: Optional[str] = None,   # ISO timestamp upper bound
+    after: Optional[str] = None,    # ISO timestamp lower bound
+) -> list[dict]:
+    """
+    Collects observations across all (folder, agent) pairs from KV.folders index.
+    Filters applied if folder_path or agent_id are provided.
+    Sorts by timestamp descending.
+    Returns at most `limit` entries.
+    """
+```
+
+---
+
+### Component 6: `folder_graph_build()` — Graph Data
+
+**Purpose**: Build the graph payload for the viewer's Graph tab.
+
+```python
+def folder_graph_build(kv: StateKV) -> dict:
+    """
+    Nodes: one per unique folder_path that has at least one (folder, agent) entry.
+    Node fields: {id, label, folderPath, agentIds, obsCount, color (from folderColor())}
+
+    Edges:
+      - Same-parent edge: two folders sharing the same parent directory.
+      - Cross-reference edge: folder A's observations mention folder B's path.
+      - Agent-shared edge: two folders have the same agentId with observations.
+
+    Returns: {"nodes": [...], "edges": [...]}
+    """
+```
+
+---
+
+### Component 7: `remember()` / `forget()` — Global Memories (unchanged interface)
+
+These functions remain as-is. `remember()` performs Jaccard deduplication at > 0.7 threshold and versions memories (`isLatest`, `parentId`). `forget()` now accepts either `memoryId` for global memories, or `folderPath` + `agentId` (+ optional `observationIds`) to delete folder observations.
+
+**Updated `forget()` signature**:
+
+```python
+def forget(kv: StateKV, data: dict) -> dict:
+    """
+    Accepts:
+        memoryId: str                — delete a global memory
+        folderPath + agentId: str    — delete all observations for that (folder, agent)
+        folderPath + agentId + observationIds: list[str]  — delete specific obs
+    """
+```
+
+---
+
+### Component 8: `health_check()` / `export_data()` — Diagnostics
+
+**`health_check()`** updated to report folder counts instead of session counts:
+
+```python
+{
+    "status": "ok",
+    "folderCount": int,       # distinct folder paths with memory
+    "agentCount": int,        # distinct agent IDs
+    "pairCount": int,         # (folder, agent) pairs
+    "observationCount": int,  # total observations across all pairs
+    "memoryCount": int,       # global memories
+    "bm25IndexSize": int,
+    "vectorIndexSize": int,
+    "dbPath": str,
+}
+```
+
+**`export_data()`** updated structure:
+
+```python
+{
+    "folders": [
+        {
+            "folderPath": str,
+            "agentId": str,
+            "meta": FolderMeta,
+            "observations": [FolderObservation, ...]
+        }
+    ],
+    "memories": [Memory, ...],
+    "exportedAt": str,
+    "version": "2.0",
+}
+```
+
+---
+
+## Data Models
+
+### FolderObservation
+
+```python
+{
+    "id": str,            # "fobs_<ts>_<rand12>"
+    "folderPath": str,    # "/Users/alice/projects/my-app/src"  (normalized, forward slashes)
+    "agentId": str,       # "kiro" | "claude" | "cursor" | any string
+    "timestamp": str,     # "2025-01-15T10:30:00.000Z"
+    "text": str,          # sanitized text, max 4000 chars
+    "type": str,          # same infer_type() values as current: "file_edit", "command_run", etc.
+    "title": str,         # ≤ 80 chars, auto-generated from text if absent
+    "concepts": list,     # ["auth", "middleware"]
+    "files": list,        # ["src/app.py", "src/db.py"]
+    "importance": int,    # 1–10
+}
+```
+
+**Validation rules**:
+- `folderPath` must be non-empty after normalization
+- `agentId` must be non-empty after stripping
+- `text` must be non-empty before stripping; after `strip_private_data()` may contain `[REDACTED]`
+- `timestamp` must be a parseable ISO 8601 string
+- `importance` clamped to 1–10 range
+
+### FolderMeta
+
+```python
+{
+    "folderPath": str,
+    "agentId": str,
+    "lastUpdated": str,   # ISO timestamp
+    "obsCount": int,      # incremented on each observation
+    "summary": str | None,
+}
+```
+
+### FolderIndexEntry (stored in `mem:folders`)
+
+```python
+# key = "{safe_folder_path}:{agent_id}"
+{
+    "folderPath": str,
+    "agentId": str,
+    "lastUpdated": str,
+    "obsCount": int,
+}
+```
+
+### Memory (unchanged)
+
+```python
+{
+    "id": str,
+    "createdAt": str,
+    "updatedAt": str,
+    "type": str,          # "fact" | "preference" | "architecture" | "bug" | "workflow" | "pattern"
+    "title": str,
+    "content": str,
+    "concepts": list,
+    "files": list,
+    "strength": int,      # 1–10
+    "version": int,
+    "parentId": str | None,
+    "supersedes": list,
+    "isLatest": bool,
+    "agentId": str | None,
+    "project": str | None,  # optional — retained for backward compat during migration
+}
+```
+
+---
+
+## Algorithmic Pseudocode
+
+### Main Observation Ingestion Algorithm
+
+```pascal
+ALGORITHM folder_observe(kv, payload)
+INPUT:  payload dict with folderPath, agentId, text, timestamp, [type, title, concepts, files, importance]
+OUTPUT: {"observationId": obs_id}
+
+BEGIN
+  ASSERT payload.folderPath IS NOT EMPTY
+  ASSERT payload.agentId IS NOT EMPTY
+  ASSERT payload.text IS NOT EMPTY
+  ASSERT payload.timestamp IS valid ISO 8601
+
+  // 1. Normalize and sanitize
+  folder_path ← normalize_path(payload.folderPath)       // os.path.normpath, forward-slashes
+  agent_id    ← payload.agentId.strip()
+  safe_text   ← strip_private_data(payload.text)
+  safe_text   ← safe_text[:4000]                          // hard cap
+
+  // 2. Build observation
+  obs_id ← generate_id("fobs")
+  obs ← {
+    id:         obs_id,
+    folderPath: folder_path,
+    agentId:    agent_id,
+    timestamp:  payload.timestamp,
+    text:       safe_text,
+    type:       payload.type OR infer_type(safe_text),
+    title:      payload.title OR safe_text[:80],
+    concepts:   payload.concepts OR [],
+    files:      extract_files(payload) OR [],
+    importance: CLAMP(payload.importance OR 5, 1, 10),
+  }
+
+  // 3. Persist observation
+  obs_scope ← KV.folder_obs(folder_path, agent_id)
+  kv.set(obs_scope, obs_id, obs)
+
+  // 4. Upsert folder metadata
+  meta_scope ← KV.folder_meta(folder_path, agent_id)
+  meta ← kv.get(meta_scope, "meta") OR {folderPath: folder_path, agentId: agent_id, obsCount: 0}
+  meta.obsCount    ← meta.obsCount + 1
+  meta.lastUpdated ← payload.timestamp
+  kv.set(meta_scope, "meta", meta)
+
+  // 5. Upsert global folders index
+  index_key ← f"{folder_path}:{agent_id}"
+  kv.set(KV.folders, index_key, {folderPath: folder_path, agentId: agent_id,
+                                  lastUpdated: meta.lastUpdated, obsCount: meta.obsCount})
+
+  // 6. Index for search
+  _bm25_index.add(obs)
+  IF embedding_provider IS NOT NULL THEN
+    vector_index_add_guarded(obs_id, folder_path, obs.title + " " + obs.text, {})
+  END IF
+
+  IF _index_persistence IS NOT NULL THEN
+    _index_persistence.schedule_save()
+  END IF
+
+  // 7. Audit + broadcast
+  kv.commit_version(f"folder_observe: {obs_id}", agent_id)
+  broadcast_stream({"type": "folder_observation", "folderPath": folder_path, "agentId": agent_id, "data": obs})
+
+  RETURN {"observationId": obs_id}
+END
+```
+
+**Preconditions:**
+- `payload` contains non-empty `folderPath`, `agentId`, `text`, `timestamp`
+- `kv` is an initialized `StateKV` instance
+
+**Postconditions:**
+- Observation is written to `KV.folder_obs(folder_path, agent_id)` under `obs_id`
+- `KV.folder_meta(folder_path, agent_id)` has `obsCount` incremented and `lastUpdated` set
+- `KV.folders` index has an entry for `(folder_path, agent_id)`
+- BM25 index contains `obs_id`
+- Audit log contains one new entry
+
+**Loop invariants:** N/A (no loops in the main path)
+
+---
+
+### Folder Timeline Algorithm
+
+```pascal
+ALGORITHM folder_timeline(kv, limit, folder_path?, agent_id?, before?, after?)
+INPUT:  optional filters; limit defaults to 100
+OUTPUT: list of FolderObservation sorted by timestamp DESC
+
+BEGIN
+  index_entries ← kv.list(KV.folders)
+
+  // Apply folder/agent filters to index
+  IF folder_path IS NOT NULL THEN
+    index_entries ← FILTER index_entries WHERE entry.folderPath = folder_path
+  END IF
+  IF agent_id IS NOT NULL THEN
+    index_entries ← FILTER index_entries WHERE entry.agentId = agent_id
+  END IF
+
+  all_obs ← []
+
+  FOR each entry IN index_entries DO
+    // Loop invariant: all_obs contains only observations that match filters applied so far
+    obs_scope ← KV.folder_obs(entry.folderPath, entry.agentId)
+    obs_list  ← kv.list(obs_scope)
+
+    // Apply timestamp filters
+    IF before IS NOT NULL THEN
+      obs_list ← FILTER obs_list WHERE obs.timestamp < before
+    END IF
+    IF after IS NOT NULL THEN
+      obs_list ← FILTER obs_list WHERE obs.timestamp > after
+    END IF
+
+    all_obs.extend(obs_list)
+  END FOR
+
+  all_obs.sort(key=lambda o: o.timestamp, reverse=True)
+  RETURN all_obs[:limit]
+END
+```
+
+**Preconditions:**
+- `kv` is initialized
+- `limit` ≥ 1
+
+**Postconditions:**
+- Returns at most `limit` observations
+- All returned observations satisfy the provided filter conditions
+- Results are ordered by `timestamp` descending
+
+**Loop invariant:** After each iteration, `all_obs` contains only observations from folders/agents matching the filter; all observations are within the timestamp range if filters were given.
+
+---
+
+### Folder Graph Build Algorithm
+
+```pascal
+ALGORITHM folder_graph_build(kv)
+INPUT:  none (reads from KV)
+OUTPUT: {nodes: list[GraphNode], edges: list[GraphEdge]}
+
+BEGIN
+  index_entries ← kv.list(KV.folders)
+
+  // Build node map keyed by folder_path
+  folder_map ← {}                // folder_path → {folderPath, agentIds: set, obsCount, color}
+  pair_obs_texts ← {}            // (folder_path, agent_id) → concatenated obs text
+
+  FOR each entry IN index_entries DO
+    fp ← entry.folderPath
+    IF fp NOT IN folder_map THEN
+      folder_map[fp] ← {folderPath: fp, agentIds: set(), obsCount: 0, color: folderColor(fp)}
+    END IF
+    folder_map[fp].agentIds.add(entry.agentId)
+    folder_map[fp].obsCount ← folder_map[fp].obsCount + entry.obsCount
+
+    // Collect obs text for cross-reference edge detection
+    obs_list ← kv.list(KV.folder_obs(fp, entry.agentId))
+    combined ← JOIN [o.text + " " + o.title FOR o IN obs_list]
+    pair_obs_texts[(fp, entry.agentId)] ← combined
+  END FOR
+
+  nodes ← [build_node(fp, info) FOR fp, info IN folder_map.items()]
+
+  edges ← []
+  folder_paths ← list(folder_map.keys())
+
+  // Edge type 1: same-parent edges
+  FOR i IN range(len(folder_paths)) DO
+    FOR j IN range(i+1, len(folder_paths)) DO
+      // Loop invariant: all pairs (a, b) with a < j and b ≤ j have been evaluated
+      a ← folder_paths[i]
+      b ← folder_paths[j]
+      IF parent(a) = parent(b) THEN
+        edges.append({source: a, target: b, type: "same-parent"})
+      END IF
+    END FOR
+  END FOR
+
+  // Edge type 2: cross-reference edges (folder A's text mentions folder B's path)
+  FOR (fp_a, agent_a), text_a IN pair_obs_texts.items() DO
+    FOR fp_b IN folder_paths DO
+      IF fp_b ≠ fp_a AND fp_b IN text_a THEN
+        IF NOT edge_exists(edges, fp_a, fp_b, "cross-ref") THEN
+          edges.append({source: fp_a, target: fp_b, type: "cross-ref"})
+        END IF
+      END IF
+    END FOR
+  END FOR
+
+  // Edge type 3: agent-shared edges (two folders with same agent)
+  agent_to_folders ← group folder_paths by agentIds
+  FOR agent_id, fps IN agent_to_folders.items() DO
+    FOR i IN range(len(fps)) DO
+      FOR j IN range(i+1, len(fps)) DO
+        edges.append({source: fps[i], target: fps[j], type: "agent-shared", agentId: agent_id})
+      END FOR
+    END FOR
+  END FOR
+
+  RETURN {nodes: nodes, edges: DEDUPLICATE(edges)}
+END
+```
+
+**Preconditions:** `kv` is initialized; `KV.folders` may be empty (returns `{nodes: [], edges: []}`)
+
+**Postconditions:**
+- One node per unique `folder_path` in `KV.folders`
+- Edges only connect distinct nodes
+- No duplicate edges (same source, target, type)
+
+---
+
+## Key Functions with Formal Specifications
+
+### `normalize_folder_path(path: str) -> str`
+
+```python
+def normalize_folder_path(path: str) -> str
+```
+
+**Preconditions:** `path` is a non-empty string
+**Postconditions:**
+- Returns path with OS separators replaced by `/`
+- No leading or trailing slashes
+- `os.path.normpath` applied (resolves `..`, double slashes)
+- Result is non-empty
+
+### `folder_observe(kv, payload) -> dict`
+
+**Preconditions:** `kv` initialized; `payload` has `folderPath`, `agentId`, `text`, `timestamp`
+**Postconditions:**
+- `result["observationId"]` is a string matching pattern `fobs_*`
+- `kv.get(KV.folder_obs(fp, aid), result["observationId"])` returns the stored obs
+- `kv.get(KV.folder_meta(fp, aid), "meta")["obsCount"]` is incremented by 1
+- `kv.get(KV.folders, f"{fp}:{aid}")` is non-None
+
+### `folder_timeline(kv, limit, ...) -> list`
+
+**Preconditions:** `kv` initialized; `limit ≥ 1`
+**Postconditions:**
+- `len(result) ≤ limit`
+- `all(result[i]["timestamp"] >= result[i+1]["timestamp"] for i in range(len(result)-1))`
+- If `folder_path` filter set: all `result[i]["folderPath"] == folder_path`
+- If `agent_id` filter set: all `result[i]["agentId"] == agent_id`
+
+### `forget(kv, data) -> dict`
+
+**Preconditions:** At least one of `memoryId`, `folderPath+agentId` is present
+**Postconditions:**
+- If `memoryId` given: `kv.get(KV.memories, memoryId)` returns None
+- If `folderPath+agentId` given (no obs IDs): all observations in `KV.folder_obs(fp, aid)` are deleted; `KV.folders` index entry is removed; `KV.folder_meta(fp, aid)` is deleted
+- `result["deleted"]` equals number of items actually removed from storage
+
+---
+
+## Migration Strategy from Current Schema
+
+### Migration Approach: Non-Destructive Lazy Read
+
+The migration does not require a destructive DB transformation at startup. Instead:
+
+1. **New data** is written using the folder-based schema immediately after deployment.
+2. **Old session data** is left in the DB under its original scopes (`mem:sessions`, `mem:obs:*`, etc.) and can be optionally migrated via a `POST /agentmemory/migrate` endpoint.
+3. The search index rebuild (`rebuild_index()`) is updated to read from both old observation scopes and new folder observation scopes — this ensures the BM25 index is populated regardless of which format data exists in.
+
+### Migration Endpoint
+
+```pascal
+ALGORITHM migrate_sessions_to_folders(kv, dry_run=False)
+INPUT:  kv, dry_run flag
+OUTPUT: {migrated_sessions, migrated_observations, errors}
+
+BEGIN
+  sessions ← kv.list("mem:sessions")
+  migrated_sessions ← 0
+  migrated_observations ← 0
+  errors ← []
+
+  FOR each session IN sessions DO
+    folder_path ← session.cwd OR session.project OR "unknown"
+    agent_id    ← session.agentId OR "unknown"
+    obs_list    ← kv.list(KV.observations(session.id))      // "mem:obs:{session_id}"
+
+    FOR each obs IN obs_list DO
+      IF obs.id ends with ":raw" THEN CONTINUE END IF   // skip raw duplicates
+
+      folder_obs ← {
+        id:         obs.id,
+        folderPath: normalize_folder_path(folder_path),
+        agentId:    agent_id,
+        timestamp:  obs.timestamp,
+        text:       obs.narrative OR obs.title OR "",
+        type:       obs.type OR "other",
+        title:      obs.title OR "",
+        concepts:   obs.concepts OR [],
+        files:      obs.files OR [],
+        importance: obs.importance OR 5,
+      }
+
+      IF NOT dry_run THEN
+        kv.set(KV.folder_obs(folder_path, agent_id), obs.id, folder_obs)
+        migrated_observations ← migrated_observations + 1
+      END IF
+    END FOR
+
+    IF NOT dry_run THEN
+      // Upsert metadata + index
+      upsert_folder_meta(kv, folder_path, agent_id, len(obs_list), session.updatedAt)
+      migrated_sessions ← migrated_sessions + 1
+    END IF
+  END FOR
+
+  RETURN {migrated_sessions, migrated_observations, errors}
+END
+```
+
+**The old scopes are never deleted automatically** — they can be cleaned up manually after verifying the migration via `POST /agentmemory/migrate?cleanup=true`.
+
+---
+
+## MCP Tools: Kept, Renamed, and Dropped
+
+### Kept / Repurposed (same tool name, redirected to folder storage)
+
+| 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 |
+
+### New Tools
+
+| 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 |
+
+### 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`
+
+---
+
+## Viewer Dashboard Restructure
+
+### New Tab Structure
+
+| Tab | Content |
+|-----|---------|
+| **Folders** | List all `(folder, agent)` pairs — shows `folderPath`, `agentId`, `obsCount`, `lastUpdated`. Click a row to drill into that pair's observations. |
+| **Memories** | Unchanged — global long-term memories with search |
+| **Graph** | Force-directed graph where nodes = folder paths, edges = same-parent / cross-ref / agent-shared relationships. Uses existing `folderColor()` function. |
+| **Timeline** | All observations across all pairs, sorted by timestamp desc. Filter bar: folder path (text match), agent dropdown. |
+
+### Removed Tabs
+
+Sessions, Lessons, Slots, Actions, Replay, Profile, Crystals
+
+### Viewer Data Endpoints (New REST calls)
+
+```
+GET  /agentmemory/folders                         → [{folderPath, agentId, obsCount, lastUpdated}]
+GET  /agentmemory/folder/observations?folderPath=&agentId=  → {observations: [...]}
+POST /agentmemory/timeline                        → {observations: [...]}  (body: {folderPath?, agentId?, limit?, before?, after?})
+GET  /agentmemory/graph                           → {nodes: [...], edges: [...]}
+```
+
+### Folders Tab — Drill-Down Detail View
+
+When a `(folder, agent)` row is clicked:
+- Header shows `folderPath` + `agentId` badge
+- Observations listed chronologically (oldest first), each showing `timestamp`, `type` badge, `title`, `text` excerpt
+- `summary` field shown if present (LLM or auto-generated)
+- "Delete folder memory" button calls `POST /agentmemory/forget` with `{folderPath, agentId}`
+
+---
+
+## Error Handling
+
+### Error Scenario 1: Missing Required Fields in `agent_observe`
+
+**Condition**: `folderPath`, `agentId`, or `text` missing from payload  
+**Response**: HTTP 400 `{"error": "folderPath, agentId, and text are required"}`  
+**Recovery**: Agent retries with all required fields
+
+### Error Scenario 2: Observation Cap Reached
+
+**Condition**: `(folder_path, agent_id)` pair has reached `MAX_OBS_PER_FOLDER` (env var, default 2000)  
+**Response**: HTTP 400 `{"error": "Folder observation limit reached (2000)"}`  
+**Recovery**: Agent calls `memory_forget` to prune old observations, or increases the cap
+
+### Error Scenario 3: Path Traversal Attempt
+
+**Condition**: `folderPath` contains `..` that after normalization escapes expected boundaries  
+**Response**: HTTP 400 `{"error": "Invalid folderPath"}`  
+**Recovery**: Agent provides an absolute, non-traversal path
+
+### Error Scenario 4: Search Index Empty on Startup
+
+**Condition**: BM25 index is empty (fresh install or corrupted shard)  
+**Response**: Search returns empty results; background thread rebuilds index from all folder observations  
+**Recovery**: Automatic — `rebuild_index()` iterates `KV.folders` index and re-adds all observations
+
+### Error Scenario 5: Migration Endpoint Failure
+
+**Condition**: Old session data is malformed or a session has no `cwd`/`project`  
+**Response**: `errors` list in migration response captures per-session failures; migration continues for other sessions  
+**Recovery**: Manual cleanup; old scopes remain untouched
+
+---
+
+## Testing Strategy
+
+### Unit Testing Approach
+
+Use `pytest`. No test runner currently configured — add `pytest` to `requirements.txt` dev deps.
+
+Key unit test targets:
+- `normalize_folder_path()`: edge cases (Windows paths, trailing slashes, `..` segments, UNC paths)
+- `strip_private_data()`: existing coverage patterns + folder-path-specific cases
+- `folder_observe()`: required field validation, obs ID generation, meta increment, index upsert
+- `forget()` with folder targets: verifies all scopes cleaned up
+- `folder_timeline()`: timestamp ordering, filter correctness, limit enforcement
+- `folder_graph_build()`: node deduplication, edge type correctness, empty case
+
+### Property-Based Testing Approach
+
+Use `hypothesis` for:
+- Any `normalize_folder_path(p)` — result is always a non-empty string with no trailing slash
+- `folder_timeline()` result is always sorted (timestamps non-increasing)
+- `folder_observe()` followed by `forget()` leaves zero observations for that pair
+
+### Integration Testing Approach
+
+End-to-end test using a temp SQLite DB:
+1. Call `folder_observe()` with 3 different `(folder, agent)` combinations
+2. Assert all 3 are returned by `folder_timeline()` in correct order
+3. Assert `folder_search("some keyword")` returns the matching observation
+4. Assert `folder_graph_build()` produces 3 nodes and correct edges
+5. Call `forget({folderPath, agentId})` and assert observations deleted from search index
+
+---
+
+## Performance Considerations
+
+- **Observation scope keys**: `mem:folder:{path}:{agent}` keys can become very long for deep paths. The `kv.list()` call uses `SELECT ... WHERE scope = ?` which is an exact match — long scope strings are fine for SQLite. The `idx_kv_scope` index on `kv_store(scope)` ensures O(log N) lookup.
+- **Timeline query cost**: Reading all observations across all folders is O(total_observations). For large deployments, this is mitigated by the `limit` cap and the timestamp filter being applied in Python (post-fetch). A future optimization is to add a `ts` column to `kv_store` for SQL-level filtering.
+- **Graph build cost**: `folder_graph_build()` does full text scanning of observations for cross-reference edges. This is acceptable for the viewer (user-triggered) but should not run on every request. Cache the graph payload with a 30-second TTL or invalidate on any new `folder_observe()`.
+- **BM25 rebuild**: `rebuild_index()` iterates all scopes. With the new schema, it must iterate `KV.folders` index entries and load each pair's observations — same O(N) complexity as before.
+- **Existing search.py and IndexPersistence are unchanged** — no performance regression in the search pipeline.
+
+---
+
+## Security Considerations
+
+- **Path normalization** before storage prevents `..` traversal in KV scope keys. `os.path.normpath()` is called before any KV write.
+- **`strip_private_data()`** is called on `text` before storage — same patterns as current (API keys, JWTs, Bearer tokens, etc.).
+- **Auth**: All new endpoints follow the existing `check_auth()` pattern using `hmac.compare_digest`.
+- **Scope injection**: `folder_path` and `agent_id` are embedded in KV scope strings. Both are normalized (control chars stripped, length capped at 512 chars) before scope construction to prevent scope collision or injection via crafted path strings.
+- **`MAX_OBS_PER_FOLDER`** cap prevents unbounded storage growth per pair, mitigating denial-of-service via observation flooding.
+
+---
+
+## Dependencies
+
+All dependencies are already present in `requirements.txt`. No new packages required:
+
+| Package | Used for |
+|---------|----------|
+| `flask` | REST server |
+| `flask-sock` | WebSocket broadcaster |
+| `python-dateutil` | ISO timestamp parsing in timeline filters |
+| `huggingface_hub` | HF Space sync (unchanged) |
+
+Optional (already supported):
+| Package | Used for |
+|---------|----------|
+| `requests` | Gemini embedding API calls |
+| `jieba` | CJK segmentation in BM25 tokenizer |
+
+New dev dependency for tests:
+| Package | Used for |
+|---------|----------|
+| `pytest` | Unit and integration tests |
+| `hypothesis` | Property-based tests |
+
+---
+
+## Correctness Properties
+
+The following properties must hold universally across the system:
+
+### Property 1: Pair Isolation
+
+For all `(folder_path_a, agent_a)` and `(folder_path_b, agent_b)` where the pairs are distinct, observations written to pair A are never returned when reading pair B's observations directly.
+
+`∀ a ≠ b: kv.list(KV.folder_obs(a)) ∩ kv.list(KV.folder_obs(b)) = ∅`
+
+### Property 2: Observation Count Consistency
+
+After any sequence of `folder_observe()` calls for a pair, `KV.folder_meta(fp, aid)["obsCount"]` equals the number of observations stored in `KV.folder_obs(fp, aid)`.
+
+`obsCount = len(kv.list(KV.folder_obs(fp, aid)))`
+
+### Property 3: Index Coverage
+
+Every `(folder_path, agent_id)` pair that has at least one observation is present in the global `KV.folders` index.
+
+`∀ (fp, aid): len(kv.list(KV.folder_obs(fp, aid))) > 0 ⟹ kv.get(KV.folders, f"{fp}:{aid}") IS NOT NULL`
+
+### Property 4: Privacy Invariant
+
+No observation stored in `KV.folder_obs(fp, aid)` contains a string matching any pattern in `SECRET_PATTERN_SOURCES`. Text is sanitized by `strip_private_data()` before every write.
+
+### Property 5: Timeline Ordering
+
+`folder_timeline()` always returns results in non-increasing timestamp order.
+
+`∀ i < j in result: result[i].timestamp ≥ result[j].timestamp`
+
+### Property 6: Forget Completeness
+
+After `forget({folderPath: fp, agentId: aid})` with no specific `observationIds` completes: `kv.list(KV.folder_obs(fp, aid))` is empty, `kv.get(KV.folders, f"{fp}:{aid}")` is None, and the BM25 index contains no entries originating from that pair.
+
+### Property 7: Memory Versioning
+
+At most one memory with a given conceptual content (Jaccard similarity > 0.7) has `isLatest = True` at any point in time. All superseded versions have `isLatest = False` and `parentId` set.
+
+### Property 8: Path Normalization Idempotency
+
+`normalize_folder_path` is idempotent: applying it twice produces the same result as applying it once.
+
+`normalize_folder_path(normalize_folder_path(p)) == normalize_folder_path(p)` for all non-empty strings `p`.
+
+### Property 9: Search Index Sync
+
+Every observation added via `folder_observe()` is present in `_bm25_index` under its `obs_id`. Every observation deleted via `forget()` is absent from `_bm25_index` after the operation completes.
+
+### Property 10: Graph Node Uniqueness
+
+`folder_graph_build()` produces exactly one node per distinct `folder_path` in `KV.folders`, regardless of how many `agent_id` values are associated with that folder path.

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

@@ -0,0 +1,141 @@
+# Requirements: Folder-Based Memory
+
+## Overview
+
+This document specifies the requirements for restructuring agentmemory-python from a session-based architecture to a folder-based memory model. The primary unit of storage shifts from `(session_id)` to `(folder_path, agent_id)` — each agent accumulates observations scoped to the folder it is working in, with no concept of "sessions". Long-term global memories remain unchanged. The viewer, MCP tools, and REST API are all reshaped around this model.
+
+The redesign eliminates sessions, lessons, slots, actions, crystals, and artefacts entirely. What remains is: folder observations, global memories, BM25 + optional vector search, a folder-based graph, a folder activity feed (timeline), privacy stripping, and the MCP tool-calling interface.
+
+---
+
+## Group 1 — Data Model
+
+- **REQ-001:** The system SHALL store observations scoped to `(folder_path, agent_id)` pairs, replacing the existing session-based `(session_id)` scope.
+- **REQ-002:** The system SHALL normalize all folder paths using `os.path.normpath`, converting OS separators to forward slashes and stripping leading/trailing slashes before any storage or scope construction.
+- **REQ-003:** Each observation SHALL contain the following fields: `id`, `folderPath`, `agentId`, `timestamp`, `text`, `type`, `title`, `concepts`, `files`, and `importance`.
+- **REQ-004:** The system SHALL maintain a global folders index stored in the `mem:folders` KV scope, keyed by the string `"{folder_path}:{agent_id}"`, containing `folderPath`, `agentId`, `lastUpdated`, and `obsCount`.
+- **REQ-005:** The system SHALL maintain per-pair metadata in a `mem:foldermeta:{folder_path}:{agent_id}` KV scope containing `folderPath`, `agentId`, `lastUpdated`, `obsCount`, and an optional `summary` field.
+- **REQ-006:** Global memories stored in the `mem:memories` scope SHALL remain unchanged from the current implementation, including their data model, versioning behaviour, and Jaccard deduplication.
+- **REQ-007:** The system SHALL cap observation `text` at 4000 characters before storage.
+
+---
+
+## Group 2 — Observation Ingestion (`agent_observe`)
+
+- **REQ-008:** The `agent_observe` endpoint SHALL require the fields `folderPath`, `agentId`, `text`, and `timestamp`; requests missing any of these fields SHALL be rejected with an error response.
+- **REQ-009:** The system SHALL call `strip_private_data()` on the observation text before any storage or indexing operation.
+- **REQ-010:** The system SHALL generate a unique observation ID with the prefix `fobs_` for every new observation.
+- **REQ-011:** The system SHALL upsert the `mem:folders` index entry for the `(folder_path, agent_id)` pair on every successful observation write.
+- **REQ-012:** The system SHALL add each new observation to the BM25 index, and to the vector index if an embedding provider is configured.
+- **REQ-013:** The system SHALL broadcast each new observation via the existing WebSocket mechanism to connected viewers.
+- **REQ-014:** The system SHALL write an audit log entry in `mem:audit` for each observation ingestion.
+- **REQ-015:** The system SHALL enforce a per-pair observation cap (`MAX_OBS_PER_FOLDER`, default 2000, configurable via environment variable); ingestion SHALL be rejected when the cap is reached.
+
+---
+
+## Group 3 — Search
+
+- **REQ-016:** The system SHALL support hybrid BM25 + vector search across all folder observations, combining scores via Reciprocal Rank Fusion (RRF) using the existing `HybridSearch` implementation.
+- **REQ-017:** Search SHALL accept optional `folderPath` and `agentId` filter parameters and restrict results to matching pairs when provided.
+- **REQ-018:** Search results SHALL also include matching global memories from `mem:memories` alongside folder observations.
+- **REQ-019:** Each search result SHALL include `folderPath`, `agentId`, `score`, and the full observation object.
+
+---
+
+## Group 4 — Timeline
+
+- **REQ-020:** The system SHALL provide a folder activity feed that returns observations sorted by `timestamp` descending.
+- **REQ-021:** The timeline SHALL support filtering by `folderPath`, `agentId`, `before` (ISO 8601 timestamp upper bound), and `after` (ISO 8601 timestamp lower bound).
+- **REQ-022:** The timeline SHALL respect a `limit` parameter (default 100) and return at most that many observations.
+
+---
+
+## Group 5 — Graph
+
+- **REQ-023:** The system SHALL build a graph where each unique `folder_path` (regardless of how many agents have observations in it) is represented as exactly one node.
+- **REQ-024:** Each graph node SHALL contain the fields `id`, `label`, `folderPath`, `agentIds` (list of all agents with observations in that folder), `obsCount`, and `color` (derived via the existing `folderColor()` hash function).
+- **REQ-025:** The system SHALL create "same-parent" edges between any two folder nodes that share the same parent directory.
+- **REQ-026:** The system SHALL create "cross-reference" edges between folder A and folder B when the text or title of any observation in folder A contains folder B's path string.
+- **REQ-027:** The system SHALL create "agent-shared" edges between any two folder nodes that have at least one common `agentId` with observations.
+- **REQ-028:** The graph SHALL contain no duplicate edges; an edge is a duplicate if it shares the same `source`, `target`, and `type` as an existing edge.
+
+---
+
+## Group 6 — Forget / Delete
+
+- **REQ-029:** The `forget` function SHALL accept a `memoryId` parameter to delete a single global memory from `mem:memories`.
+- **REQ-030:** The `forget` function SHALL accept a `folderPath` + `agentId` pair to delete all observations stored for that pair.
+- **REQ-031:** The `forget` function SHALL accept a `folderPath` + `agentId` pair together with a list of `observationIds` to delete only the specified observations.
+- **REQ-032:** When a full `(folderPath, agentId)` pair is deleted, the system SHALL remove its entry from the `mem:folders` index, delete the `mem:foldermeta:{path}:{agent}` scope, and remove all corresponding entries from the BM25 index.
+- **REQ-033:** The response from any `forget` operation SHALL include a `"deleted"` field containing the count of items actually removed from storage.
+
+---
+
+## Group 7 — Viewer (4 Tabs Only)
+
+- **REQ-034:** The viewer dashboard SHALL contain exactly four tabs: Folders, Memories, Graph, and Timeline.
+- **REQ-035:** The Folders tab SHALL list all `(folder, agent)` pairs, displaying `folderPath`, `agentId`, `obsCount`, and `lastUpdated` for each.
+- **REQ-036:** Clicking a row in the Folders tab SHALL display a drill-down view showing all observations for that `(folderPath, agentId)` pair.
+- **REQ-037:** The Memories tab SHALL be functionally unchanged from the current implementation.
+- **REQ-038:** The Graph tab SHALL render a force-directed graph using the folder-based node and edge model defined in Group 5.
+- **REQ-039:** The Timeline tab SHALL display observations from all pairs sorted by timestamp descending, with filter controls for folder path and agent ID.
+- **REQ-040:** The following tabs SHALL be removed from the viewer: Sessions, Lessons, Slots, Actions, Replay, Profile, and Crystals.
+
+---
+
+## Group 8 — MCP Tools
+
+- **REQ-041:** The `agent_observe` MCP tool SHALL require `folderPath`, `agentId`, and `text`; a `sessionId` parameter MAY be accepted for backward compatibility but SHALL be ignored.
+- **REQ-042:** The `memory_recall` MCP tool SHALL search folder observations and global memories, accepting optional `folderPath` and `agentId` filter parameters.
+- **REQ-043:** The `memory_save` and `agent_remember` MCP tools SHALL continue to save to global memories without change.
+- **REQ-044:** The `memory_smart_search` MCP tool SHALL perform hybrid BM25 + vector search equivalent to `memory_recall`.
+- **REQ-045:** The `memory_export` MCP tool SHALL export all folder pairs with their observations and all global memories in the v2 export format (version `"2.0"`).
+- **REQ-046:** The `memory_forget` MCP tool SHALL accept either a `memoryId` (global memory deletion) or a `folderPath` + `agentId` pair (folder observations deletion).
+- **REQ-047:** The `memory_diagnose` MCP tool SHALL return `folderCount`, `agentCount`, `pairCount`, `observationCount`, and `memoryCount` instead of session-based counts.
+- **REQ-048:** A new `memory_folders` MCP tool SHALL be added that lists all `(folder, agent)` pairs with `folderPath`, `agentId`, `obsCount`, and `lastUpdated`.
+- **REQ-049:** A new `memory_folder_observations` MCP tool SHALL be added that returns all observations for a specified `(folderPath, agentId)` pair.
+- **REQ-050:** A new `memory_timeline` MCP tool SHALL be added that returns the folder activity feed, supporting the same filter parameters as the timeline REST endpoint.
+- **REQ-051:** The following MCP tools SHALL be removed: `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`, and `memory_antigravity_sync_all`.
+
+---
+
+## Group 9 — REST Endpoints
+
+- **REQ-052:** The system SHALL expose `GET /agentmemory/folders` to return a list of all `(folder, agent)` pairs from the `mem:folders` index.
+- **REQ-053:** The system SHALL expose `GET /agentmemory/folder/observations` accepting `folderPath` and `agentId` query parameters and returning all observations for that pair.
+- **REQ-054:** The system SHALL expose `POST /agentmemory/timeline` accepting an optional JSON body with `folderPath`, `agentId`, `limit`, `before`, and `after` fields, and returning the folder activity feed.
+- **REQ-055:** The system SHALL expose `GET /agentmemory/graph` returning the graph payload with `nodes` and `edges` arrays.
+- **REQ-056:** The system SHALL expose `POST /agentmemory/migrate` to migrate old session-based data to the folder format, supporting a `dry_run` boolean parameter.
+- **REQ-057:** All new endpoints SHALL enforce `AGENTMEMORY_SECRET` Bearer token authentication using `hmac.compare_digest`, consistent with the existing `check_auth()` pattern; the `/livez` endpoint SHALL remain unauthenticated.
+
+---
+
+## Group 10 — Migration
+
+- **REQ-058:** The `POST /agentmemory/migrate` endpoint SHALL read from the existing `mem:sessions` and `mem:obs:{session_id}` KV scopes to retrieve legacy session data.
+- **REQ-059:** Migration SHALL map `session.cwd` or `session.project` to `folderPath`, and `session.agentId` to `agentId`; missing values SHALL fall back to the string `"unknown"`.
+- **REQ-060:** Migration SHALL be non-destructive: old `mem:sessions` and `mem:obs:*` scopes SHALL never be automatically deleted during or after migration.
+- **REQ-061:** Migration SHALL support a `dry_run=true` mode that computes and returns migration counts without writing any data.
+- **REQ-062:** The migration response SHALL include the fields `migrated_sessions`, `migrated_observations`, and `errors`.
+
+---
+
+## Group 11 — Security & Privacy
+
+- **REQ-063:** The system SHALL apply `os.path.normpath` to all folder paths before using them in any KV scope key construction.
+- **REQ-064:** The system SHALL reject with HTTP 400 any request where the normalized folder path contains path traversal patterns (e.g. `..`).
+- **REQ-065:** The system SHALL call `strip_private_data()` on all observation text before storage, indexing, or broadcast.
+- **REQ-066:** The system SHALL length-cap `agent_id` and `folder_path` values at 512 characters before using them in any KV scope key construction.
+- **REQ-067:** All new REST endpoints SHALL use the existing `check_auth()` / `hmac.compare_digest` authentication pattern.
+
+---
+
+## Group 12 — Correctness Properties
+
+- **REQ-068:** The system SHALL guarantee pair isolation: a direct read of `KV.folder_obs(folder_path_A, agent_id_A)` SHALL never return observations belonging to a different `(folder_path, agent_id)` pair.
+- **REQ-069:** The system SHALL guarantee observation count consistency: the `obsCount` value stored in `KV.folder_meta(folder_path, agent_id)` SHALL always equal the actual number of observation keys present in `KV.folder_obs(folder_path, agent_id)`.
+- **REQ-070:** The system SHALL guarantee index coverage: every `(folder_path, agent_id)` pair that has at least one stored observation SHALL have a corresponding entry in the `mem:folders` index.
+- **REQ-071:** The system SHALL guarantee timeline ordering: all results returned by `folder_timeline()` SHALL be in non-increasing `timestamp` order (i.e. `result[i].timestamp >= result[i+1].timestamp` for all valid `i`).
+- **REQ-072:** The system SHALL guarantee forget completeness: after a full `(folderPath, agentId)` pair deletion, the BM25 index SHALL contain no document entries originating from that pair.
+- **REQ-073:** The system SHALL guarantee memory version uniqueness: at most one memory with a Jaccard similarity greater than 0.7 to any other memory SHALL have `isLatest=True` at any point in time.
+- **REQ-074:** The system SHALL guarantee path normalization idempotency: applying `normalize_folder_path()` twice to any input SHALL produce the same result as applying it once — i.e. `normalize_folder_path(normalize_folder_path(p)) == normalize_folder_path(p)`.

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

@@ -0,0 +1,320 @@
+# Implementation Plan: Folder-Based Memory
+
+## Overview
+
+Restructure agentmemory-python from session-based to folder-based memory. The primary unit
+of storage shifts from `(session_id)` to `(folder_path, agent_id)`. Core business logic
+(`functions.py`) is rewritten first; REST endpoints and MCP tools (`app.py`) are updated
+next; finally the viewer (`index.html`) is rebuilt to four tabs: Folders, Memories, Graph,
+Timeline. A migration endpoint and a pytest + hypothesis test suite round out the work.
+
+---
+
+## Tasks
+
+- [x] 1. Rewrite KV scope registry and core helpers in `src/functions.py`
+  - [x] 1.1 Replace the `KV` class with the folder-based scope definitions
+    - Remove all session/lesson/slot/action/crystal/sketch/facet/sentinel/signal/checkpoint/mesh/routine scopes
+    - Add `KV.folders = "mem:folders"`, `KV.folder_obs(folder_path, agent_id)`, `KV.folder_meta(folder_path, agent_id)`
+    - Keep `KV.memories`, `KV.bm25Index`, `KV.audit`; keep `KV.relations` (repurposed for graph edges)
+    - _Requirements: REQ-001, REQ-004, REQ-005_
+
+  - [x] 1.2 Add `normalize_folder_path()` utility function
+    - Apply `os.path.normpath`, convert OS separators to `/`, strip leading/trailing slashes
+    - Reject (raise `ValueError`) if the normalized path contains `..` segments
+    - Cap `folder_path` and `agent_id` at 512 characters before any scope construction
+    - _Requirements: REQ-002, REQ-063, REQ-064, REQ-066_
+
+  - [ ]* 1.3 Write property test for `normalize_folder_path` — idempotency
+    - **Property 8: Path Normalization Idempotency**
+    - **Validates: REQ-074 / Requirements REQ-002**
+    - Use `hypothesis.strategies.text()` with a mix of Windows and POSIX path strings
+    - Assert `normalize_folder_path(normalize_folder_path(p)) == normalize_folder_path(p)` for all valid inputs
+
+- [x] 2. Implement `folder_observe()` — observation ingestion
+  - [x] 2.1 Write `folder_observe(kv, payload) -> dict` in `src/functions.py`
+    - Validate required fields: `folderPath`, `agentId`, `text`, `timestamp`; raise `ValueError` if missing
+    - Normalize `folder_path` via `normalize_folder_path()`; strip and validate `agent_id`
+    - Call `strip_private_data(text)` before any storage; cap text at 4000 chars
+    - Generate `obs_id = generate_id("fobs")`; build `FolderObservation` dict with all fields
+    - Write to `KV.folder_obs(folder_path, agent_id)` under `obs_id`
+    - Upsert `KV.folder_meta` (`obsCount += 1`, update `lastUpdated`); upsert `KV.folders` index entry
+    - Add to `_bm25_index`; call `vector_index_add_guarded` if provider set; schedule persistence save
+    - Write audit log entry via `kv.commit_version`; broadcast via `broadcast_stream`
+    - Enforce `MAX_OBS_PER_FOLDER` cap (default 2000, env-configurable); raise `ValueError` if reached
+    - _Requirements: REQ-003, REQ-007, REQ-008, REQ-009, REQ-010, REQ-011, REQ-012, REQ-013, REQ-014, REQ-015_
+
+  - [ ]* 2.2 Write property test for `folder_observe` — pair isolation
+    - **Property 1: Pair Isolation**
+    - **Validates: REQ-068**
+    - Generate two distinct `(folderPath, agentId)` pairs via `hypothesis`; write one observation to each
+    - Assert `kv.list(KV.folder_obs(a)) ∩ kv.list(KV.folder_obs(b)) = ∅`
+
+  - [ ]* 2.3 Write property test for `folder_observe` — observation count consistency
+    - **Property 2: Observation Count Consistency**
+    - **Validates: REQ-069**
+    - Generate N random observations for a pair (N drawn from `hypothesis.strategies.integers(1, 20)`)
+    - Assert `kv.get(KV.folder_meta(fp, aid), "meta")["obsCount"] == len(kv.list(KV.folder_obs(fp, aid)))`
+
+  - [ ]* 2.4 Write property test for `folder_observe` — index coverage
+    - **Property 3: Index Coverage**
+    - **Validates: REQ-070**
+    - After writing at least one observation for a pair, assert `kv.get(KV.folders, f"{fp}:{aid}")` is not None
+
+  - [ ]* 2.5 Write property test for `folder_observe` — privacy invariant
+    - **Property 4: Privacy Invariant**
+    - **Validates: REQ-009 / REQ-065**
+    - Inject strings matching `SECRET_PATTERN_SOURCES` patterns into `text`; call `folder_observe`
+    - Assert no stored observation's `text` field matches any secret pattern
+
+- [x] 3. Implement `folder_search()`, `folder_timeline()`, and `folder_graph_build()`
+  - [x] 3.1 Write `folder_search(kv, query, limit, folder_path?, agent_id?) -> list` in `src/functions.py`
+    - Delegate to existing `_hybrid_search.search(query, limit * 2)` for BM25 + vector scoring
+    - Hydrate each `obs_id` from `KV.folder_obs` scopes; include matching global memories from `KV.memories`
+    - Apply `folder_path` / `agent_id` post-filters; include `folderPath`, `agentId`, `score` in each result
+    - _Requirements: REQ-016, REQ-017, REQ-018, REQ-019_
+
+  - [x] 3.2 Write `folder_timeline(kv, limit, folder_path?, agent_id?, before?, after?) -> list`
+    - List all entries from `KV.folders`; apply folder/agent filters; load observations from each pair
+    - Apply `before` / `after` ISO timestamp filters; sort all results by `timestamp` descending; return `[:limit]`
+    - _Requirements: REQ-020, REQ-021, REQ-022_
+
+  - [ ]* 3.3 Write property test for `folder_timeline` — ordering guarantee
+    - **Property 5: Timeline Ordering**
+    - **Validates: REQ-071**
+    - Generate an arbitrary set of observations with random timestamps; call `folder_timeline(kv, limit=1000)`
+    - Assert `all(result[i]["timestamp"] >= result[i+1]["timestamp"] for i in range(len(result)-1))`
+
+  - [x] 3.4 Write `folder_graph_build(kv) -> dict`
+    - Build one node per unique `folder_path` in `KV.folders`; aggregate `agentIds` and `obsCount`; assign color via `folderColor(folder_path)` hash
+    - Produce three edge types: `"same-parent"` (shared parent dir), `"cross-ref"` (folder B's path mentioned in folder A's obs text/title), `"agent-shared"` (two folders share an `agentId`)
+    - Deduplicate edges on `(source, target, type)`; return `{"nodes": [...], "edges": [...]}`
+    - _Requirements: REQ-023, REQ-024, REQ-025, REQ-026, REQ-027, REQ-028_
+
+  - [ ]* 3.5 Write property test for `folder_graph_build` — node uniqueness
+    - **Property 10: Graph Node Uniqueness**
+    - **Validates: REQ-073 / Requirements REQ-023**
+    - Generate observations in multiple `(folder, agent)` combinations sharing some folder paths
+    - Assert `len(nodes) == len({entry["folderPath"] for entry in kv.list(KV.folders)})`
+
+- [x] 4. Update `forget()` and `health_check()` / `export_data()` in `src/functions.py`
+  - [x] 4.1 Rewrite `forget(kv, data) -> dict` to handle folder-based deletion
+    - If `memoryId` present: delete from `KV.memories` (existing logic, unchanged)
+    - If `folderPath + agentId` present (no `observationIds`): delete all entries in `KV.folder_obs(fp, aid)`, remove BM25 index entries for each `obs_id`, delete `KV.folder_meta` entry, remove `KV.folders` index entry; set `result["deleted"]`
+    - If `folderPath + agentId + observationIds` present: delete only specified observations, decrement `obsCount` in metadata
+    - _Requirements: REQ-029, REQ-030, REQ-031, REQ-032, REQ-033_
+
+  - [ ]* 4.2 Write property test for `forget` — completeness
+    - **Property 6: Forget Completeness**
+    - **Validates: REQ-072**
+    - Write N observations for a pair; call `forget({folderPath, agentId})`
+    - Assert `kv.list(KV.folder_obs(fp, aid)) == []`, `kv.get(KV.folders, key) is None`, and no BM25 entry matches any `obs_id` from that pair
+
+  - [x] 4.3 Update `health_check(kv) -> dict` to return folder-based counts
+    - Return `folderCount` (distinct folder paths), `agentCount`, `pairCount`, `observationCount`, `memoryCount`, `bm25IndexSize`, `vectorIndexSize`, `dbPath`
+    - Remove session-based fields
+    - _Requirements: REQ-047_
+
+  - [x] 4.4 Update `export_data(kv, opts) -> dict` to v2 folder format
+    - Output `{"folders": [{folderPath, agentId, meta, observations: [...]}], "memories": [...], "exportedAt": ..., "version": "2.0"}`
+    - _Requirements: REQ-045_
+
+  - [x] 4.5 Update `rebuild_index(kv)` to read from folder observation scopes
+    - Iterate `KV.folders` index entries; load each pair's observations via `KV.folder_obs`; re-add to BM25 and vector indexes
+    - _Requirements: REQ-016_
+
+- [x] 5. Checkpoint — verify core business logic
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 6. Update REST endpoints in `src/app.py`
+  - [x] 6.1 Rewrite `POST /agentmemory/agent/observe` to call `folder_observe()`
+    - Require `folderPath`, `agentId`, `text`; accept `sessionId` for backward compat (ignore it)
+    - Validate with HTTP 400 if required fields are missing; pass through `folderPath`, `agentId`, `text`, `timestamp`, `type`, `title`, `concepts`, `files`, `importance`
+    - _Requirements: REQ-008, REQ-041, REQ-057_
+
+  - [x] 6.2 Update `POST /agentmemory/search` to call `folder_search()`
+    - Accept optional `folderPath` and `agentId` in request body; pass to `folder_search()`
+    - _Requirements: REQ-016, REQ-017, REQ-057_
+
+  - [ ] 6.3 Add `GET /agentmemory/folders` endpoint
+    - Return `kv.list(KV.folders)` sorted by `lastUpdated` descending
+    - _Requirements: REQ-052, REQ-057_
+
+  - [x] 6.4 Add `GET /agentmemory/folder/observations` endpoint
+    - Accept `folderPath` and `agentId` query params (both required); return `{"observations": [...]}`
+    - Reject with HTTP 400 if either param is missing
+    - _Requirements: REQ-053, REQ-057_
+
+  - [x] 6.5 Add `POST /agentmemory/timeline` endpoint
+    - Accept optional JSON body `{folderPath?, agentId?, limit?, before?, after?}`; delegate to `folder_timeline()`
+    - _Requirements: REQ-054, REQ-057_
+
+  - [x] 6.6 Add `GET /agentmemory/graph` endpoint
+    - Delegate to `folder_graph_build(kv)`; return `{"nodes": [...], "edges": [...]}`
+    - _Requirements: REQ-055, REQ-057_
+
+  - [x] 6.7 Add `POST /agentmemory/migrate` endpoint
+    - Accept optional `dry_run` boolean in body; delegate to `migrate_sessions_to_folders(kv, dry_run)`
+    - Return `{migrated_sessions, migrated_observations, errors}`
+    - _Requirements: REQ-056, REQ-057, REQ-058, REQ-059, REQ-060, REQ-061, REQ-062_
+
+  - [x] 6.8 Implement `migrate_sessions_to_folders(kv, dry_run=False)` in `src/functions.py`
+    - Read `kv.list("mem:sessions")`; for each session, map `cwd` or `project` → `folderPath`, `agentId` with `"unknown"` fallback
+    - Skip `:raw` observations; build `FolderObservation` from session obs fields; write if not dry-run
+    - Upsert folder metadata and index entries; never delete old `mem:sessions` or `mem:obs:*` scopes
+    - Collect per-session errors; return `{migrated_sessions, migrated_observations, errors}`
+    - _Requirements: REQ-058, REQ-059, REQ-060, REQ-061, REQ-062_
+
+  - [x] 6.9 Remove or stub out session-based endpoints that have no folder equivalent
+    - Remove/stub: `POST /session/start`, `POST /session/end`, `POST /session/commit`, `GET /session/by-commit`, `GET /sessions`, `GET /observations` (session-scoped), `GET /replay/sessions`
+    - Remove/stub: lessons endpoints (`/lessons`, `/lessons/search`, `/lessons/strengthen`), slots endpoints (`/slot`, `/slots`, `/slot/append`, `/slot/replace`), antigravity endpoints
+    - Remove background worker calls to `lesson_decay_sweep` and `consolidate` from `init_app()`
+    - _Requirements: REQ-040, REQ-051_
+
+- [x] 7. Update MCP tool schema and dispatch in `src/app.py`
+  - [x] 7.1 Update `agent_observe` MCP tool schema and handler
+    - Change required fields to `folderPath`, `agentId`, `text`; mark `sessionId` as optional/deprecated
+    - Handler calls `folder_observe(kv, args)`
+    - _Requirements: REQ-041_
+
+  - [x] 7.2 Update `memory_recall` and `memory_smart_search` MCP tool schemas and handlers
+    - Add optional `folderPath` and `agentId` parameters; handlers call `folder_search()`
+    - _Requirements: REQ-042, REQ-044_
+
+  - [x] 7.3 Update `memory_export`, `memory_forget`, `memory_diagnose` MCP handlers
+    - `memory_export` calls updated `export_data()` → v2 format
+    - `memory_forget` accepts `memoryId` OR `folderPath + agentId`; calls updated `forget()`
+    - `memory_diagnose` calls updated `health_check()` → folder counts
+    - _Requirements: REQ-045, REQ-046, REQ-047_
+
+  - [x] 7.4 Add `memory_folders`, `memory_folder_observations`, `memory_timeline` MCP tools
+    - `memory_folders`: no required args; returns `kv.list(KV.folders)`
+    - `memory_folder_observations`: requires `folderPath`, `agentId`; returns observations for that pair
+    - `memory_timeline`: optional `folderPath`, `agentId`, `limit`, `before`, `after`; calls `folder_timeline()`
+    - _Requirements: REQ-048, REQ-049, REQ-050_
+
+  - [x] 7.5 Remove dropped MCP tools from schema and dispatch
+    - Remove from `GET /mcp/tools` list and `POST /mcp/tools` dispatch: `memory_sessions`, `memory_sessions_list`, `memory_observations` (session), `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`
+    - _Requirements: REQ-051_
+
+- [x] 8. Checkpoint — verify REST and MCP layer
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 9. Rebuild viewer dashboard to four tabs in `src/viewer/index.html`
+  - [x] 9.1 Remove old tabs and restructure tab bar to exactly four tabs
+    - Replace current tab bar entries with: Folders, Memories, Graph, Timeline
+    - Remove tab panes and JS sections for: Sessions, Lessons, Slots, Actions, Replay, Profile, Crystals
+    - Update `<div class="tab-bar">` and the `showTab()` / active-tab JS logic accordingly
+    - _Requirements: REQ-034, REQ-040_
+
+  - [x] 9.2 Implement Folders tab — list view and drill-down detail
+    - On load, fetch `GET /agentmemory/folders`; render table rows with `folderPath`, `agentId`, `obsCount`, `lastUpdated`
+    - On row click, fetch `GET /agentmemory/folder/observations?folderPath=&agentId=`; render observations list with `timestamp`, type badge, `title`, `text` excerpt
+    - Show `summary` field if present; add "Delete folder memory" button that calls `POST /agentmemory/forget`
+    - _Requirements: REQ-035, REQ-036_
+
+  - [x] 9.3 Preserve Memories tab functionality (no logic change)
+    - Verify existing Memories tab code still works against `GET /agentmemory/memories` and `POST /agentmemory/remember`
+    - Update any session-specific references (e.g. session filter dropdowns) to remove or replace with folder filters
+    - _Requirements: REQ-037_
+
+  - [x] 9.4 Implement Graph tab with folder-based nodes and edges
+    - Fetch `GET /agentmemory/graph`; render force-directed graph using existing canvas + physics code
+    - Nodes keyed by `folderPath`; color via existing `folderColor()` function; node label = basename of `folderPath`
+    - Render three edge types with distinct stroke styles: `same-parent` (dashed), `cross-ref` (solid), `agent-shared` (dotted)
+    - Update graph sidebar filter checkboxes to match the three new edge types
+    - _Requirements: REQ-038_
+
+  - [x] 9.5 Implement Timeline tab with folder activity feed
+    - Fetch `POST /agentmemory/timeline` with `{limit: 100}` on tab activate; render observation cards sorted newest-first
+    - Add filter bar: text input for `folderPath` substring match, dropdown for `agentId` (populated from `GET /agentmemory/folders`)
+    - On filter change, re-fetch timeline with updated body params; support `before`/`after` via existing date-range controls pattern
+    - _Requirements: REQ-039_
+
+  - [x] 9.6 Update WebSocket handler to process `folder_observation` broadcast events
+    - Change the `type == "compressed_observation"` / `type == "raw_observation"` branch to also handle `type == "folder_observation"`
+    - On receive, append to the Timeline tab live feed if it is active; update Folders tab obsCount badge if that folder is visible
+    - _Requirements: REQ-013_
+
+- [x] 10. Update supporting files
+  - [x] 10.1 Update `requirements.txt` to add `pytest` and `hypothesis`
+    - Add `pytest==8.3.5` and `hypothesis==6.131.15` under a `# dev` comment
+    - _Requirements: design testing strategy_
+
+  - [x] 10.2 Update `start.sh` to remove session-based startup logic
+    - Remove any session auto-complete or lesson-decay invocations from startup
+    - _Requirements: REQ-040, REQ-051_
+
+  - [x] 10.3 Update `sync.py` if it references session-scoped KV keys
+    - Replace any hardcoded `mem:sessions` or `mem:obs:*` references with `mem:folders` and `mem:folder:*` patterns for backup filtering
+    - _Requirements: REQ-004_
+
+- [x] 11. Write pytest + hypothesis test suite
+  - [x] 11.1 Create `tests/test_normalize.py` — unit tests for `normalize_folder_path`
+    - Test Windows paths (`C:\Users\foo`), POSIX paths, paths with `..`, UNC paths, trailing slashes, empty string (expect `ValueError`)
+    - _Requirements: REQ-002, REQ-063_
+
+  - [x] 11.2 Create `tests/test_folder_observe.py` — unit tests for `folder_observe`
+    - Test missing required fields raise `ValueError`; test obs ID prefix `fobs_`; test `obsCount` increment; test `KV.folders` index upsert; test `MAX_OBS_PER_FOLDER` cap
+    - _Requirements: REQ-008, REQ-010, REQ-011, REQ-015_
+
+  - [x] 11.3 Create `tests/test_forget.py` — unit tests for `forget`
+    - Test full pair deletion clears all three scopes; test partial deletion by `observationIds`; test `deleted` count in response
+    - _Requirements: REQ-029, REQ-030, REQ-031, REQ-032, REQ-033_
+
+  - [x] 11.4 Create `tests/test_timeline.py` — unit tests for `folder_timeline`
+    - Test `before`/`after` filters; test `limit` enforcement; test empty result when no data
+    - _Requirements: REQ-020, REQ-021, REQ-022_
+
+  - [x] 11.5 Create `tests/test_graph.py` — unit tests for `folder_graph_build`
+    - Test empty KV returns `{nodes: [], edges: []}`; test one node per unique folder; test same-parent edge; test no duplicate edges
+    - _Requirements: REQ-023, REQ-025, REQ-028_
+
+  - [x] 11.6 Create `tests/test_migration.py` — unit tests for `migrate_sessions_to_folders`
+    - Test `dry_run=True` writes nothing; test `cwd`/`project` fallback to `"unknown"`; test `:raw` obs are skipped; test `errors` list populated on malformed sessions
+    - _Requirements: REQ-058, REQ-059, REQ-060, REQ-061, REQ-062_
+
+  - [ ]* 11.7 Create `tests/test_properties.py` — all Hypothesis property tests
+    - **Property 1: Pair Isolation** (REQ-068)
+    - **Property 2: Observation Count Consistency** (REQ-069)
+    - **Property 3: Index Coverage** (REQ-070)
+    - **Property 4: Privacy Invariant** (REQ-065)
+    - **Property 5: Timeline Ordering** (REQ-071)
+    - **Property 6: Forget Completeness** (REQ-072)
+    - **Property 7: Memory Version Uniqueness** (REQ-073)
+    - **Property 8: Path Normalization Idempotency** (REQ-074)
+    - **Property 10: Graph Node Uniqueness** (REQ-023)
+    - Use a temp-file SQLite DB (`tmp_path` fixture) for each test; isolate with `@given` + `@settings(max_examples=50)`
+
+- [x] 12. Final checkpoint — full test run
+  - Ensure all tests pass (`pytest tests/`), ask the user if questions arise.
+
+---
+
+## Notes
+
+- Tasks marked with `*` are optional and can be skipped for a faster MVP
+- Each task references specific requirements for traceability
+- The migration endpoint (task 6.8) is non-destructive: old `mem:sessions` / `mem:obs:*` data is never deleted
+- Property tests in `tests/test_properties.py` (task 11.7) consolidate all Hypothesis tests; the earlier inline property test tasks (1.3, 2.2–2.5, 3.3, 3.5, 4.2) are equivalent sub-sets and can be skipped if 11.7 is implemented
+- `src/db.py` schema is unchanged — only KV scope strings change, not the SQLite table structure
+- The `folderColor()` function referenced by the Graph tab and `folder_graph_build()` is the existing hash-to-HSL function already in `index.html`; it should be extracted or duplicated into `functions.py` for server-side use
+
+## Task Dependency Graph
+
+```json
+{
+  "waves": [
+    { "id": 0, "tasks": ["1.1", "1.2"] },
+    { "id": 1, "tasks": ["1.3", "2.1"] },
+    { "id": 2, "tasks": ["2.2", "2.3", "2.4", "2.5", "3.1", "3.2", "4.1"] },
+    { "id": 3, "tasks": ["3.3", "3.4", "4.2", "4.3", "4.4", "4.5"] },
+    { "id": 4, "tasks": ["3.5", "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.8"] },
+    { "id": 5, "tasks": ["6.7", "6.9", "7.1", "7.2", "7.3"] },
+    { "id": 6, "tasks": ["7.4", "7.5", "9.1", "10.1", "10.2", "10.3"] },
+    { "id": 7, "tasks": ["9.2", "9.3", "9.4", "9.5"] },
+    { "id": 8, "tasks": ["9.6", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6"] },
+    { "id": 9, "tasks": ["11.7"] }
+  ]
+}
+```

requirements.txt

@@ -4,3 +4,7 @@ requests>=2.31.0
 websockets>=12.0
 python-dateutil>=2.8.2
 huggingface_hub>=0.20.0
+
+# dev
+pytest==8.3.5
+hypothesis==6.131.15

src/app.py

@@ -125,27 +125,8 @@ def init_app():
                 print(f"[scheduler] auto_forget loop error: {e}")
             time.sleep(3600)
 
-    def run_consolidation_loop():
-        time.sleep(15)
-        while True:
-            try:
-                print("[scheduler] Running lesson_decay_sweep...")
-                decay_res = functions.lesson_decay_sweep(kv)
-                print(f"[scheduler] lesson_decay_sweep completed: {decay_res}")
-                
-                if functions.is_consolidation_enabled():
-                    print("[scheduler] Running consolidation...")
-                    cons_res = functions.consolidate(kv)
-                    print(f"[scheduler] consolidation completed: {cons_res}")
-            except Exception as e:
-                print(f"[scheduler] consolidation/decay loop error: {e}")
-            time.sleep(86400)
-
     t_forget = threading.Thread(target=run_auto_forget_loop, daemon=True)
     t_forget.start()
-    
-    t_consolidate = threading.Thread(target=run_consolidation_loop, daemon=True)
-    t_consolidate.start()
 
 # =====================================================================
 # Auth Middleware
@@ -339,44 +320,36 @@ def api_agent_observe():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
+
     try:
         body = request.get_json(force=True) or {}
+        folder_path = body.get("folderPath")
         agent_id = body.get("agentId")
-        session_id = body.get("sessionId")
-        project = body.get("project")
-        cwd = body.get("cwd") or ""
         text = body.get("text") or body.get("content") or ""
-        obs_type = body.get("type") or "other"
-        title = body.get("title") or f"agent_{obs_type}"
-        image_data = body.get("imageData")
-        
-        if not session_id or not project:
-            return jsonify({"error": "sessionId and project are required"}), 400
-            
-        timestamp = datetime_now_iso()
-        
-        data_payload = {
-            "tool_name": title,
-            "tool_input": text,
-            "tool_output": text,
-        }
-        if image_data:
-            data_payload["imageBase64"] = image_data
-            
+
+        if not folder_path or not agent_id or not text:
+            return jsonify({"error": "folderPath, agentId, and text are required"}), 400
+
+        # sessionId accepted but ignored (folder-based model)
+        # timestamp defaults to now UTC
+        timestamp = body.get("timestamp") or datetime_now_iso()
+
         payload = {
-            "sessionId": session_id,
-            "project": project,
-            "cwd": cwd,
-            "hookType": "post_tool_use",
+            "folderPath": folder_path,
+            "agentId": agent_id,
+            "text": text,
             "timestamp": timestamp,
-            "data": data_payload
+            "type": body.get("type"),
+            "title": body.get("title"),
+            "concepts": body.get("concepts"),
+            "files": body.get("files"),
+            "importance": body.get("importance"),
         }
-        if agent_id:
-            payload["agentId"] = agent_id
-            
-        res = functions.observe(kv, payload)
+
+        res = functions.folder_observe(kv, payload)
         return jsonify(res), 201
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400
     except Exception as e:
         return jsonify({"error": str(e)}), 400
 
@@ -399,17 +372,17 @@ def api_search():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
+
     try:
         body = request.get_json(force=True) or {}
         query = body.get("query")
         if not query or not query.strip():
             return jsonify({"error": "query is required"}), 400
         limit = body.get("limit") or 10
-        
-        # smart search / hybrid search query
-        res = functions._hybrid_search.search(query, limit)
-        res = enrich_search_results(kv, res)
+        folder_path = body.get("folderPath")
+        agent_id = body.get("agentId")
+
+        res = functions.folder_search(kv, query, limit, folder_path=folder_path, agent_id=agent_id)
         return jsonify(res), 200
     except Exception as e:
         return jsonify({"error": str(e)}), 400
@@ -432,165 +405,27 @@ def api_export():
 
 @app.route("/agentmemory/replay/sessions", methods=["GET"])
 def api_replay_sessions():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    sessions = functions.list_sessions(kv)
-    return jsonify({"success": True, "sessions": sessions}), 200
+    return jsonify({"error": "Gone — session replay removed in folder-based memory model"}), 410
 
 @app.route("/agentmemory/session/start", methods=["POST"])
 def api_session_start():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        session_id = body.get("sessionId")
-        project = body.get("project")
-        cwd = body.get("cwd")
-        if not session_id or not project or not cwd:
-            return jsonify({"error": "sessionId, project, and cwd are required"}), 400
-            
-        title = body.get("title")
-        agent_id = body.get("agentId") or functions.get_agent_id()
-        
-        session = {
-            "id": session_id,
-            "project": project,
-            "cwd": cwd,
-            "startedAt": datetime_now_iso(),
-            "status": "active",
-            "observationCount": 0
-        }
-        if title:
-            session["summary"] = title[:200]
-            session["firstPrompt"] = title[:200]
-        if agent_id:
-            session["agentId"] = agent_id
-            
-        functions.create_session(kv, session)
-        
-        # Compile initial context
-        ctx = functions.context(kv, {"sessionId": session_id, "project": project})
-        
-        # Commit to Dolt
-        functions.commit_if_enabled(kv, f"Start session {session_id[:8]}", agent_id)
-        
-        return jsonify({"session": session, "context": ctx.get("context", "")}), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/antigravity/sync", methods=["POST"])
 def api_antigravity_sync():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-    try:
-        body = request.get_json(force=True) or {}
-        mode = body.get("mode") or "current_session"
-        current_convo = body.get("currentConversationId")
-        current_folder = body.get("currentFolder")
-        res = perform_antigravity_sync(mode, current_convo, current_folder)
-        return jsonify(res), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 500
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/session/end", methods=["POST"])
 def api_session_end():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        session_id = body.get("sessionId")
-        if not session_id:
-            return jsonify({"error": "sessionId is required"}), 400
-            
-        functions.end_session(kv, session_id)
-        
-        # Commit to Dolt
-        sess = functions.get_session(kv, session_id) or {}
-        agent_id = sess.get("agentId")
-        functions.commit_if_enabled(kv, f"End session {session_id[:8]}", agent_id)
-        
-        return jsonify({"success": True}), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/session/commit", methods=["POST"])
 def api_session_commit():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        sha = body.get("sha")
-        if not sha:
-            return jsonify({"error": "sha is required"}), 400
-            
-        session_id = body.get("sessionId")
-        branch = body.get("branch")
-        repo = body.get("repo")
-        message = body.get("message")
-        author = body.get("author")
-        authored_at = body.get("authoredAt")
-        files = body.get("files")
-        
-        existing = kv.get(KV.commits, sha) or {}
-        session_ids = set(existing.get("sessionIds", []))
-        if session_id:
-            session_ids.add(session_id)
-            
-        link = {
-            "sha": sha,
-            "shortSha": sha[:7],
-            "branch": branch or existing.get("branch"),
-            "repo": repo or existing.get("repo"),
-            "message": message or existing.get("message"),
-            "author": author or existing.get("author"),
-            "authoredAt": authored_at or existing.get("authoredAt"),
-            "files": files or existing.get("files"),
-            "sessionIds": list(session_ids),
-            "linkedAt": existing.get("linkedAt") or datetime_now_iso()
-        }
-        kv.set(KV.commits, sha, link)
-        
-        if session_id:
-            sess = functions.get_session(kv, session_id)
-            if sess:
-                commit_shas = set(sess.get("commitShas", []))
-                commit_shas.add(sha)
-                sess["commitShas"] = list(commit_shas)
-                functions.create_session(kv, sess)
-                
-        return jsonify({"commit": link}), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/session/by-commit", methods=["GET"])
 def api_session_by_commit():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    sha = request.args.get("sha")
-    if not sha:
-        return jsonify({"error": "sha query param required"}), 400
-        
-    link = kv.get(KV.commits, sha)
-    if not link:
-        return jsonify({"error": "no sessions linked to this commit"}), 404
-        
-    sessions = []
-    for sid in link.get("sessionIds", []):
-        sess = functions.get_session(kv, sid)
-        if sess:
-            sessions.append(sess)
-    return jsonify({"commit": link, "sessions": sessions}), 200
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/commits", methods=["GET"])
 def api_commits():
@@ -614,20 +449,7 @@ def api_commits():
 
 @app.route("/agentmemory/sessions", methods=["GET"])
 def api_sessions():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    sessions = functions.list_sessions(kv)
-    agent_id = request.args.get("agentId")
-    if agent_id and agent_id != "*":
-        sessions = [s for s in sessions if s.get("agentId") == agent_id]
-    elif functions.is_agent_scope_isolated():
-        env_aid = functions.get_agent_id()
-        if env_aid:
-            sessions = [s for s in sessions if s.get("agentId") == env_aid]
-            
-    return jsonify({"sessions": sessions}), 200
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/observations", methods=["GET"])
 def api_observations():
@@ -717,175 +539,128 @@ def api_forget():
     except Exception as e:
         return jsonify({"error": str(e)}), 400
 
-# =====================================================================
-# Lessons Learned Endpoints
-# =====================================================================
+@app.route("/agentmemory/folders", methods=["GET"])
+def api_folders():
+    auth_err = check_auth()
+    if auth_err:
+        return auth_err
+    folders = sorted(
+        kv.list(functions.KV.folders),
+        key=lambda x: x.get("lastUpdated", ""),
+        reverse=True
+    )
+    return jsonify({"folders": folders}), 200
 
-@app.route("/agentmemory/lessons", methods=["GET"])
-def api_lessons_list():
+
+@app.route("/agentmemory/folder/observations", methods=["GET"])
+def api_folder_observations():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
-    project = request.args.get("project")
-    source = request.args.get("source")
-    min_conf = float(request.args.get("minConfidence", "0"))
-    limit = int(request.args.get("limit", "50"))
-    
-    res = functions.lesson_list(kv, {
-        "project": project,
-        "source": source,
-        "minConfidence": min_conf,
-        "limit": limit
-    })
-    return jsonify(res), 200
+    fp = request.args.get("folderPath")
+    aid = request.args.get("agentId")
+    if not fp or not aid:
+        return jsonify({"error": "folderPath and agentId are required"}), 400
+    observations = sorted(
+        kv.list(functions.KV.folder_obs(fp, aid)),
+        key=lambda x: x.get("timestamp", ""),
+        reverse=True
+    )
+    return jsonify({"observations": observations, "folderPath": fp, "agentId": aid}), 200
 
-@app.route("/agentmemory/lessons", methods=["POST"])
-def api_lessons_save():
+
+@app.route("/agentmemory/timeline", methods=["POST"])
+def api_timeline():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
     try:
         body = request.get_json(force=True) or {}
-        res = functions.lesson_save(kv, body)
-        return jsonify(res), 201 if res.get("action") == "created" else 200
+        folder_path = body.get("folderPath")
+        agent_id = body.get("agentId")
+        limit = body.get("limit") or 100
+        before = body.get("before")
+        after = body.get("after")
+        result = functions.folder_timeline(kv, limit, folder_path, agent_id, before, after)
+        return jsonify({"observations": result}), 200
     except Exception as e:
         return jsonify({"error": str(e)}), 400
 
-@app.route("/agentmemory/lessons/search", methods=["POST"])
-def api_lessons_search():
+
+@app.route("/agentmemory/graph", methods=["GET"])
+def api_graph():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        res = functions.lesson_recall(kv, body)
-        return jsonify(res), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    result = functions.folder_graph_build(kv)
+    return jsonify(result), 200
 
-@app.route("/agentmemory/lessons/strengthen", methods=["POST"])
-def api_lessons_strengthen():
+
+@app.route("/agentmemory/migrate", methods=["POST"])
+def api_migrate():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-        
     try:
         body = request.get_json(force=True) or {}
-        lesson_id = body.get("lessonId")
-        if not lesson_id:
-            return jsonify({"error": "lessonId is required"}), 400
-        res = functions.lesson_strengthen(kv, lesson_id)
-        return jsonify(res), 200
+        dry_run = bool(body.get("dry_run", False))
+        result = functions.migrate_sessions_to_folders(kv, dry_run)
+        return jsonify(result), 200
     except Exception as e:
         return jsonify({"error": str(e)}), 400
 
+
+# =====================================================================
+# Lessons Learned Endpoints (stubbed — 410 Gone)
+# =====================================================================
+
+@app.route("/agentmemory/lessons", methods=["GET"])
+def api_lessons_list():
+    return jsonify({"error": "Gone — lessons have been removed in the folder-based memory model"}), 410
+
+@app.route("/agentmemory/lessons", methods=["POST"])
+def api_lessons_save():
+    return jsonify({"error": "Gone — lessons have been removed in the folder-based memory model"}), 410
+
+@app.route("/agentmemory/lessons/search", methods=["POST"])
+def api_lessons_search():
+    return jsonify({"error": "Gone — lessons have been removed in the folder-based memory model"}), 410
+
+@app.route("/agentmemory/lessons/strengthen", methods=["POST"])
+def api_lessons_strengthen():
+    return jsonify({"error": "Gone — lessons have been removed in the folder-based memory model"}), 410
+
 # =====================================================================
-# Memory Slots Endpoints
+# Memory Slots Endpoints (stubbed — 410 Gone)
 # =====================================================================
 
 @app.route("/agentmemory/slots", methods=["GET"])
 def api_slots_list():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    return jsonify(functions.slot_list(kv)), 200
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot", methods=["GET"])
 def api_slots_get():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    label = request.args.get("label")
-    if not label:
-        return jsonify({"error": "label required"}), 400
-    res = functions.slot_get(kv, label)
-    status = 200 if res.get("success") else 404
-    return jsonify(res), status
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot", methods=["POST"])
 def api_slots_create():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        res = functions.slot_create(kv, body)
-        status = 201 if res.get("success") else 400
-        return jsonify(res), status
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot/append", methods=["POST"])
 def api_slots_append():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        label = body.get("label")
-        text = body.get("text")
-        if not label or not text:
-            return jsonify({"error": "label and text required"}), 400
-        res = functions.slot_append(kv, label, text)
-        status = 200 if res.get("success") else 400
-        return jsonify(res), status
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot/replace", methods=["POST"])
 def api_slots_replace():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        label = body.get("label")
-        content = body.get("content")
-        if not label or content is None:
-            return jsonify({"error": "label and content required"}), 400
-        res = functions.slot_replace(kv, label, content)
-        status = 200 if res.get("success") else 400
-        return jsonify(res), status
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot", methods=["DELETE"])
 def api_slots_delete():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    label = request.args.get("label")
-    if not label:
-        return jsonify({"error": "label query param required"}), 400
-    res = functions.slot_delete(kv, label)
-    status = 200 if res.get("success") else 404
-    return jsonify(res), status
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 @app.route("/agentmemory/slot/reflect", methods=["POST"])
 def api_slots_reflect():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        session_id = body.get("sessionId")
-        if not session_id:
-            return jsonify({"error": "sessionId required"}), 400
-        max_obs = body.get("maxObservations") or 50
-        res = functions.slot_reflect(kv, session_id, max_obs)
-        return jsonify(res), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+    return jsonify({"error": "Gone — slots have been removed in the folder-based memory model"}), 410
 
 # =====================================================================
 # Audit, Relations, Evolve, Timeline, Profile
@@ -938,17 +713,9 @@ def api_evolve():
         return jsonify({"error": str(e)}), 400
 
 @app.route("/agentmemory/timeline", methods=["POST"])
-def api_timeline():
-    auth_err = check_auth()
-    if auth_err:
-        return auth_err
-        
-    try:
-        body = request.get_json(force=True) or {}
-        res = functions.timeline(kv, body)
-        return jsonify(res), 200
-    except Exception as e:
-        return jsonify({"error": str(e)}), 400
+def api_timeline_legacy():
+    # Duplicate route removed — now handled by the folder-based api_timeline above.
+    return jsonify({"error": "This endpoint has been removed", "status": "gone"}), 410
 
 @app.route("/agentmemory/profile", methods=["GET"])
 def api_profile():
@@ -991,9 +758,83 @@ def api_graph_stats():
     auth_err = check_auth()
     if auth_err:
         return auth_err
-    nodes = kv.list(KV.graphNodes)
-    edges = kv.list(KV.graphEdges)
-    return jsonify({"nodes": len(nodes), "edges": len(edges), "success": True}), 200
+        
+    # Dynamically compute graph folder nodes and connection edges
+    sessions = functions.list_sessions(kv)
+    memories = kv.list(KV.memories)
+    
+    folders = set()
+    concepts_by_folder = {}
+    
+    for s in sessions:
+        project = s.get("project", "").strip()
+        if project:
+            folders.add(project)
+            
+    for m in memories:
+        project = m.get("project", "").strip()
+        if project:
+            folders.add(project)
+            concepts = m.get("concepts", [])
+            if concepts:
+                if project not in concepts_by_folder:
+                    concepts_by_folder[project] = set()
+                for c in concepts:
+                    if isinstance(c, str):
+                        concepts_by_folder[project].add(c.lower())
+                        
+    node_count = len(folders)
+    edge_count = 0
+    folder_list = list(folders)
+    
+    for i in range(len(folder_list)):
+        for j in range(i + 1, len(folder_list)):
+            f1 = folder_list[i]
+            f2 = folder_list[j]
+            
+            c1 = concepts_by_folder.get(f1, set())
+            c2 = concepts_by_folder.get(f2, set())
+            shared = c1.intersection(c2)
+            
+            p1 = [p for p in f1.replace("\\", "/").split("/") if p]
+            p2 = [p for p in f2.replace("\\", "/").split("/") if p]
+            common_subdirs = 0
+            for k in range(min(len(p1), len(p2))):
+                if p1[k].lower() == p2[k].lower():
+                    p_low = p1[k].lower()
+                    if p_low not in ("c:", "d:", "downloads", "projects", "other projects"):
+                        common_subdirs += 1
+                else:
+                    break
+                    
+            if len(shared) > 0 or common_subdirs > 0:
+                edge_count += 1
+                
+    return jsonify({"nodes": node_count, "edges": edge_count, "success": True}), 200
+
+@app.route("/agentmemory/graph/query", methods=["POST"])
+def api_graph_query():
+    auth_err = check_auth()
+    if auth_err:
+        return auth_err
+    try:
+        body = request.get_json(force=True) or {}
+        start_node_id = body.get("startNodeId")
+        return jsonify({"nodes": [], "edges": [], "success": True}), 200
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400
+
+@app.route("/agentmemory/graph/build", methods=["POST"])
+def api_graph_build():
+    auth_err = check_auth()
+    if auth_err:
+        return auth_err
+    try:
+        if functions.is_consolidation_enabled():
+            functions.consolidate(kv)
+        return jsonify({"success": True}), 200
+    except Exception as e:
+        return jsonify({"error": str(e)}), 400
 
 @app.route("/agentmemory/semantic", methods=["GET"])
 def api_semantic_list():
@@ -1629,9 +1470,10 @@ def perform_antigravity_sync(mode="current_session", current_conversation_id=Non
         return {"success": False, "syncedSessions": [], "observationsAdded": 0, "error": f"Invalid mode: {mode}"}
 
     if not targets:
-        return {"success": True, "syncedSessions": [], "observationsAdded": 0}
+        return {"success": True, "syncedSessions": [], "processedSessions": [], "observationsAdded": 0}
 
     synced_sessions = []
+    processed_sessions = []
     observations_added = 0
 
     for convo in targets:
@@ -1737,10 +1579,11 @@ def perform_antigravity_sync(mode="current_session", current_conversation_id=Non
             observations_added += 1
             convo_synced = True
 
+        processed_sessions.append(convo_id)
         if convo_synced:
             synced_sessions.append(convo_id)
 
-    return {"success": True, "syncedSessions": synced_sessions, "observationsAdded": observations_added}
+    return {"success": True, "syncedSessions": synced_sessions, "processedSessions": processed_sessions, "observationsAdded": observations_added}
 
 @app.route("/agentmemory/mcp/tools", methods=["GET"])
 def mcp_tools_list():
@@ -1751,12 +1594,28 @@ def mcp_tools_list():
     tools = [
         {
             "name": "memory_recall",
-            "description": "Search past session observations for relevant context. Use when you need to recall what happened in previous sessions.",
+            "description": "Search past folder observations and global memories. Use when you need to recall what happened in a folder.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
                     "query": {"type": "string", "description": "Search query keywords"},
-                    "limit": {"type": "number", "description": "Max results to return (default 10)"}
+                    "limit": {"type": "number", "description": "Max results to return (default 10)"},
+                    "folderPath": {"type": "string", "description": "Filter to a specific folder path (optional)"},
+                    "agentId": {"type": "string", "description": "Filter to a specific agent ID (optional)"}
+                },
+                "required": ["query"]
+            }
+        },
+        {
+            "name": "memory_smart_search",
+            "description": "Hybrid semantic+keyword search across folder observations and global memories.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "Search query"},
+                    "limit": {"type": "number", "description": "Max results (default 10)"},
+                    "folderPath": {"type": "string", "description": "Filter to a specific folder path (optional)"},
+                    "agentId": {"type": "string", "description": "Filter to a specific agent ID (optional)"}
                 },
                 "required": ["query"]
             }
@@ -1786,146 +1645,24 @@ def mcp_tools_list():
                 "required": ["content"]
             }
         },
-        {
-            "name": "memory_sessions",
-            "description": "List recent sessions with their status and observation counts.",
-            "inputSchema": {"type": "object", "properties": {}}
-        },
-        {
-            "name": "memory_sessions_list",
-            "description": "Retrieve list of all memory sessions.",
-            "inputSchema": {"type": "object", "properties": {}}
-        },
-        {
-            "name": "memory_smart_search",
-            "description": "Hybrid semantic+keyword search with progressive disclosure.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                    "limit": {"type": "number", "description": "Max results (default 10)"}
-                },
-                "required": ["query"]
-            }
-        },
-        {
-            "name": "memory_timeline",
-            "description": "Chronological observations around an anchor point.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "anchor": {"type": "string", "description": "Anchor point date or keyword"},
-                    "project": {"type": "string", "description": "Filter by project path"},
-                    "sessionId": {"type": "string", "description": "Filter by session ID"}
-                },
-                "required": ["anchor"]
-            }
-        },
-        {
-            "name": "memory_observations",
-            "description": "Retrieve all observations for a given session ID.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "sessionId": {"type": "string", "description": "Session ID to fetch observations for"}
-                },
-                "required": ["sessionId"]
-            }
-        },
-        {
-            "name": "memory_profile",
-            "description": "User/project profile with top concepts and file patterns.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "project": {"type": "string", "description": "Project path"}
-                },
-                "required": ["project"]
-            }
-        },
-        {
-            "name": "memory_lessons",
-            "description": "List all saved lessons, optionally filtered by project.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "project": {"type": "string", "description": "Filter by project (optional)"},
-                    "minConfidence": {"type": "number", "description": "Filter by minimum confidence (optional, default 0.0)"},
-                    "limit": {"type": "number", "description": "Max results to return (optional, default 50)"}
-                }
-            }
-        },
-        {
-            "name": "memory_lesson_save",
-            "description": "Save a lesson learned from this session.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "content": {"type": "string", "description": "The lesson learned"},
-                    "context": {"type": "string", "description": "When/where this lesson applies"},
-                    "project": {"type": "string", "description": "Project this lesson is about"}
-                },
-                "required": ["content"]
-            }
-        },
-        {
-            "name": "memory_lesson_recall",
-            "description": "Search lessons by query. Returns lessons sorted by confidence and recency.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query"},
-                    "project": {"type": "string", "description": "Filter by project"}
-                },
-                "required": ["query"]
-            }
-        },
-        {
-            "name": "memory_lesson_search",
-            "description": "Search lessons learned by query.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "query": {"type": "string", "description": "Search query keywords"},
-                    "project": {"type": "string", "description": "Filter by project path (optional)"}
-                },
-                "required": ["query"]
-            }
-        },
-        {
-            "name": "memory_consolidate",
-            "description": "Trigger the consolidation pipeline to summarize sessions and extract semantic/procedural memory.",
-            "inputSchema": {"type": "object", "properties": {}}
-        },
-        {
-            "name": "memory_reflect",
-            "description": "Trigger reflection for a session, updating pending items, project context, and session patterns.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "sessionId": {"type": "string", "description": "Session ID to reflect upon"},
-                    "maxObservations": {"type": "number", "description": "Max observations to scan (optional, default 50)"}
-                },
-                "required": ["sessionId"]
-            }
-        },
         {
             "name": "memory_diagnose",
-            "description": "Run diagnostic health checks across all memory subsystems.",
+            "description": "Health check — returns folder, agent, observation and memory counts.",
             "inputSchema": {"type": "object", "properties": {}}
         },
         {
             "name": "memory_forget",
-            "description": "Delete a memory, a session, or specific observations within a session.",
+            "description": "Delete a global memory or all observations for a (folderPath, agentId) pair.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
                     "memoryId": {"type": "string", "description": "Memory ID to delete"},
-                    "sessionId": {"type": "string", "description": "Session ID to delete"},
+                    "folderPath": {"type": "string", "description": "Folder path to delete observations from"},
+                    "agentId": {"type": "string", "description": "Agent ID to delete observations for"},
                     "observationIds": {
                         "oneOf": [
                             {"type": "string", "description": "Comma-separated observation IDs to delete"},
-                            {"type": "array", "items": {"type": "string"}, "description": "List of observation IDs to delete"}
+                            {"type": "array", "items": {"type": "string"}}
                         ]
                     }
                 }
@@ -1933,208 +1670,84 @@ def mcp_tools_list():
         },
         {
             "name": "memory_export",
-            "description": "Export all memory data including sessions, memories, lessons, observations, and slots as JSON.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "maxSessions": {"type": "number", "description": "Max sessions to export (optional)"},
-                    "offset": {"type": "number", "description": "Pagination offset for sessions (optional)"}
-                }
-            }
+            "description": "Export all folder observations and global memories as JSON (v2 format).",
+            "inputSchema": {"type": "object", "properties": {}}
         },
         {
             "name": "agent_observe",
-            "description": "Log a direct observation, thought, command execution, or action from the agent's active execution.",
+            "description": "Log an observation scoped to a folder path and agent ID.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
-                    "agentId": {"type": "string", "description": "ID/Name of the agent logging this (e.g. 'antigravity', optional)"},
-                    "sessionId": {"type": "string", "description": "Active session ID"},
-                    "project": {"type": "string", "description": "Canonical project path/identifier"},
-                    "text": {"type": "string", "description": "The observation log, thought, or content"},
-                    "content": {"type": "string", "description": "The observation log, thought, or content (alternative to text)"},
-                    "type": {"type": "string", "description": "Observation type: thought, command, tool, error, result, conversation, other"},
-                    "title": {"type": "string", "description": "A short summary title for the observation"},
-                    "cwd": {"type": "string", "description": "Current working directory"}
+                    "folderPath": {"type": "string", "description": "Absolute path of the working directory"},
+                    "agentId": {"type": "string", "description": "Identity of the agent (e.g. 'kiro', 'claude')"},
+                    "text": {"type": "string", "description": "Observation content"},
+                    "timestamp": {"type": "string", "description": "ISO 8601 UTC timestamp (defaults to now)"},
+                    "type": {"type": "string", "description": "Observation type"},
+                    "title": {"type": "string", "description": "Short title"},
+                    "concepts": {"type": "array", "items": {"type": "string"}},
+                    "files": {"type": "array", "items": {"type": "string"}},
+                    "importance": {"type": "integer", "description": "1-10"},
+                    "sessionId": {"type": "string", "description": "Deprecated — ignored"}
                 },
-                "required": ["sessionId", "project"]
+                "required": ["folderPath", "agentId", "text"]
             }
         },
         {
             "name": "agent_remember",
-            "description": "Explicitly save a key insight, fact, user preference, or architecture decision to long-term memory.",
+            "description": "Explicitly save a key insight, fact, or architecture decision to long-term memory.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
-                    "agentId": {"type": "string", "description": "ID/Name of the agent (e.g. 'antigravity', optional)"},
+                    "agentId": {"type": "string", "description": "ID/Name of the agent (optional)"},
                     "content": {"type": "string", "description": "The memory content/insight"},
                     "project": {"type": "string", "description": "Canonical project path/identifier"},
                     "type": {"type": "string", "description": "Memory type: fact, preference, bug, workflow, architecture"},
                     "concepts": {
                         "oneOf": [
                             {"type": "string", "description": "Comma-separated key concepts"},
-                            {"type": "array", "items": {"type": "string"}, "description": "List of key concepts"}
+                            {"type": "array", "items": {"type": "string"}}
                         ]
                     },
                     "files": {
                         "oneOf": [
                             {"type": "string", "description": "Comma-separated relevant file paths"},
-                            {"type": "array", "items": {"type": "string"}, "description": "List of relevant file paths"}
+                            {"type": "array", "items": {"type": "string"}}
                         ]
                     }
                 },
-                "required": ["content", "project"]
-            }
-        },
-        {
-            "name": "memory_antigravity_sync",
-            "description": "Sync Antigravity chat transcripts to agentmemory. Supports syncing the current session, all sessions, or sessions associated with the current folder.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "mode": {"type": "string", "description": "Sync mode: current_session (default), current_folder, or all"},
-                    "currentConversationId": {"type": "string", "description": "Optional conversation ID of the current active session"},
-                    "currentFolder": {"type": "string", "description": "Optional current folder path to filter by"}
-                },
-                "required": ["mode"]
-            }
-        },
-        {
-            "name": "memory_antigravity_sync_all",
-            "description": "Sync the current Antigravity session, automatically crystallize (summarize) it, and reflect to populate pinned memory slots in a single action.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "mode": {"type": "string", "description": "Sync mode: current_session (default), current_folder, or all"},
-                    "currentConversationId": {"type": "string", "description": "Optional conversation ID of the current active session"},
-                    "currentFolder": {"type": "string", "description": "Optional current folder path to filter by"}
-                },
-                "required": ["mode"]
+                "required": ["content"]
             }
         },
         {
-            "name": "memory_slot_list",
-            "description": "List all pinned memory slots.",
+            "name": "memory_folders",
+            "description": "List all (folder, agent) pairs that have memory observations.",
             "inputSchema": {"type": "object", "properties": {}}
         },
         {
-            "name": "memory_slot_get",
-            "description": "Retrieve the content of a specific pinned memory slot.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "label": {"type": "string", "description": "The label of the pinned slot to fetch"}
-                },
-                "required": ["label"]
-            }
-        },
-        {
-            "name": "memory_slot_create",
-            "description": "Create a new pinned memory slot or overwrite an existing one.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "label": {"type": "string", "description": "The label of the pinned slot"},
-                    "content": {"type": "string", "description": "Initial content for the slot (optional)"},
-                    "scope": {"type": "string", "description": "Scope: global or session (optional, default 'global')"},
-                    "sizeLimit": {"type": "number", "description": "Character limit (optional)"},
-                    "pinned": {"type": "boolean", "description": "Whether pinned to context (optional, default true)"}
-                },
-                "required": ["label"]
-            }
-        },
-        {
-            "name": "memory_slot_append",
-            "description": "Append text content to a pinned memory slot.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "label": {"type": "string", "description": "The label of the pinned slot"},
-                    "text": {"type": "string", "description": "Text to append"}
-                },
-                "required": ["label", "text"]
-            }
-        },
-        {
-            "name": "memory_slot_replace",
-            "description": "Replace the content of a pinned memory slot.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "label": {"type": "string", "description": "The label of the pinned slot"},
-                    "content": {"type": "string", "description": "New content"}
-                },
-                "required": ["label", "content"]
-            }
-        },
-        {
-            "name": "memory_slot_delete",
-            "description": "Delete a pinned memory slot.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "label": {"type": "string", "description": "The label of the pinned slot to delete"}
-                },
-                "required": ["label"]
-            }
-        },
-        {
-            "name": "memory_action_create",
-            "description": "Create a new work item / action.",
+            "name": "memory_folder_observations",
+            "description": "Get all observations for a specific (folderPath, agentId) pair.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
-                    "title": {"type": "string", "description": "Title of the action"},
-                    "description": {"type": "string", "description": "Detailed description of the action (optional)"},
-                    "priority": {"type": "number", "description": "Priority score, higher is more urgent (optional, default 0)"},
-                    "status": {"type": "string", "description": "Status: pending, active, completed (optional, default 'pending')"},
-                    "tags": {
-                        "oneOf": [
-                            {"type": "string", "description": "Comma-separated tags (optional)"},
-                            {"type": "array", "items": {"type": "string"}, "description": "List of tags (optional)"}
-                        ]
-                    },
-                    "sessionId": {"type": "string", "description": "Link to a specific session ID (optional)"}
+                    "folderPath": {"type": "string", "description": "Folder path"},
+                    "agentId": {"type": "string", "description": "Agent ID"}
                 },
-                "required": ["title"]
+                "required": ["folderPath", "agentId"]
             }
         },
         {
-            "name": "memory_action_update",
-            "description": "Update fields of an existing action.",
-            "inputSchema": {
-                "type": "object",
-                "properties": {
-                    "actionId": {"type": "string", "description": "ID of the action to update"},
-                    "title": {"type": "string", "description": "Updated title (optional)"},
-                    "description": {"type": "string", "description": "Updated description (optional)"},
-                    "priority": {"type": "number", "description": "Updated priority (optional)"},
-                    "status": {"type": "string", "description": "Updated status: pending, active, completed, discarded (optional)"},
-                    "tags": {
-                        "oneOf": [
-                            {"type": "string", "description": "Comma-separated tags (optional)"},
-                            {"type": "array", "items": {"type": "string"}, "description": "List of tags (optional)"}
-                        ]
-                    },
-                    "sessionId": {"type": "string", "description": "Updated session ID (optional)"}
-                },
-                "required": ["actionId"]
-            }
-        },
-        {
-            "name": "memory_frontier",
-            "description": "Get pending and active actions sorted by priority.",
-            "inputSchema": {"type": "object", "properties": {}}
-        },
-        {
-            "name": "memory_crystallize",
-            "description": "Crystallize/summarize all observations in a session.",
+            "name": "memory_timeline",
+            "description": "Get folder activity feed — observations sorted by time, filterable by folder/agent.",
             "inputSchema": {
                 "type": "object",
                 "properties": {
-                    "sessionId": {"type": "string", "description": "Session ID to crystallize"}
-                },
-                "required": ["sessionId"]
+                    "folderPath": {"type": "string", "description": "Filter by folder path (optional)"},
+                    "agentId": {"type": "string", "description": "Filter by agent ID (optional)"},
+                    "limit": {"type": "integer", "description": "Max results (default 100)"},
+                    "before": {"type": "string", "description": "ISO timestamp upper bound (optional)"},
+                    "after": {"type": "string", "description": "ISO timestamp lower bound (optional)"}
+                }
             }
         }
     ]
@@ -2160,15 +1773,15 @@ def mcp_tools_call():
         if name == "memory_recall":
             q = args.get("query")
             limit = int(args.get("limit") or 10)
-            res = functions._hybrid_search.search(q, limit)
-            res = enrich_search_results(kv, res)
+            folder_path = args.get("folderPath")
+            agent_id = args.get("agentId")
+            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":
             content = args.get("content")
             concepts = parse_mcp_list_arg(args.get("concepts"))
             files = parse_mcp_list_arg(args.get("files"))
-            session_id = args.get("sessionId")
             project = args.get("project")
             res = functions.remember(kv, {
                 "content": content,
@@ -2177,88 +1790,14 @@ def mcp_tools_call():
                 "files": files,
                 "project": project
             })
-            # If sessionId provided, also write observation so memory is linked to session
-            if session_id and project and content:
-                obs_payload = {
-                    "sessionId": session_id,
-                    "project": project,
-                    "cwd": "",
-                    "hookType": "post_tool_use",
-                    "timestamp": datetime_now_iso(),
-                    "agentId": functions.get_agent_id() or "agent",
-                    "data": {
-                        "tool_name": "memory_save",
-                        "tool_input": content[:500],
-                        "tool_output": res.get("id", ""),
-                    }
-                }
-                functions.observe(kv, obs_payload)
             text_out = json.dumps(res)
             
-        elif name in ("memory_sessions", "memory_sessions_list"):
-            sessions = functions.list_sessions(kv)
-            text_out = json.dumps({"sessions": sessions}, indent=2)
-            
         elif name == "memory_smart_search":
             q = args.get("query")
             limit = int(args.get("limit") or 10)
-            res = functions._hybrid_search.search(q, limit)
-            res = enrich_search_results(kv, res)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_timeline":
-            res = functions.timeline(kv, {
-                "anchor": args.get("anchor"),
-                "project": args.get("project"),
-                "sessionId": args.get("sessionId")
-            })
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_observations":
-            session_id = args.get("sessionId")
-            if not session_id:
-                return jsonify({"error": "sessionId is required"}), 400
-            obs = kv.list(KV.observations(session_id))
-            obs.sort(key=lambda o: o.get("timestamp", ""))
-            text_out = json.dumps({"observations": obs}, indent=2)
-
-        elif name == "memory_profile":
-            res = functions.build_project_profile(kv, args.get("project"))
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_lessons":
-            res = functions.lesson_list(kv, {
-                "project": args.get("project"),
-                "minConfidence": args.get("minConfidence"),
-                "limit": args.get("limit")
-            })
-            text_out = json.dumps(res, indent=2)
-
-        elif name == "memory_lesson_save":
-            res = functions.lesson_save(kv, {
-                "content": args.get("content"),
-                "context": args.get("context"),
-                "project": args.get("project")
-            })
-            text_out = json.dumps(res)
-            
-        elif name in ("memory_lesson_recall", "memory_lesson_search"):
-            res = functions.lesson_recall(kv, {
-                "query": args.get("query"),
-                "project": args.get("project")
-            })
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_consolidate":
-            res = functions.consolidate(kv)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_reflect":
-            session_id = args.get("sessionId")
-            max_obs = int(args.get("maxObservations") or 50)
-            if not session_id:
-                return jsonify({"error": "sessionId is required"}), 400
-            res = functions.slot_reflect(kv, session_id, max_obs)
+            folder_path = args.get("folderPath")
+            agent_id = args.get("agentId")
+            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":
@@ -2269,221 +1808,69 @@ def mcp_tools_call():
             obs_ids = parse_mcp_list_arg(args.get("observationIds"))
             res = functions.forget(kv, {
                 "memoryId": args.get("memoryId"),
-                "sessionId": args.get("sessionId"),
+                "folderPath": args.get("folderPath"),
+                "agentId": args.get("agentId"),
                 "observationIds": obs_ids
             })
             text_out = json.dumps(res, indent=2)
 
         elif name == "memory_export":
-            max_sess = args.get("maxSessions")
-            offset = args.get("offset")
-            payload = {}
-            if max_sess is not None: payload["maxSessions"] = max_sess
-            if offset is not None: payload["offset"] = offset
-            res = functions.export_data(kv, payload)
+            res = functions.export_data(kv, {})
             text_out = json.dumps(res, indent=2)
 
         elif name == "agent_observe":
-            agent_id = args.get("agentId") or functions.get_agent_id() or "agent"
-            session_id = args.get("sessionId")
-            project = args.get("project")
-            text = args.get("text") or args.get("content")
-            obs_type = args.get("type") or "other"
-            title = args.get("title") or f"agent_{obs_type}"
-            cwd = args.get("cwd") or ""
-            
-            if not session_id or not project or not text:
-                return jsonify({"error": "sessionId, project, and text (or content) are required"}), 400
-                
+            folder_path = args.get("folderPath")
+            agent_id = args.get("agentId")
+            text = args.get("text") or args.get("content") or ""
+            if not folder_path or not agent_id or not text:
+                return jsonify({"error": "folderPath, agentId, and text are required"}), 400
+            timestamp = args.get("timestamp") or datetime_now_iso()
             payload = {
-                "sessionId": session_id,
-                "project": project,
-                "cwd": cwd,
-                "hookType": "post_tool_use",
-                "timestamp": datetime_now_iso(),
-                "agentId": agent_id,
-                "data": {
-                    "tool_name": title,
-                    "tool_input": text,
-                    "tool_output": text,
-                }
+                "folderPath": folder_path, "agentId": agent_id, "text": text,
+                "timestamp": timestamp, "type": args.get("type"), "title": args.get("title"),
+                "concepts": args.get("concepts"), "files": args.get("files"),
+                "importance": args.get("importance"),
             }
-            res = functions.observe(kv, payload)
+            res = functions.folder_observe(kv, payload)
             text_out = json.dumps(res)
 
         elif name == "agent_remember":
             agent_id = args.get("agentId") or functions.get_agent_id() or "agent"
             content = args.get("content")
             project = args.get("project")
-            session_id = args.get("sessionId")
             mem_type = args.get("type") or "fact"
             concepts = parse_mcp_list_arg(args.get("concepts"))
             files = parse_mcp_list_arg(args.get("files"))
-
-            if not content or not project:
-                return jsonify({"error": "content and project are required"}), 400
-
+            if not content:
+                return jsonify({"error": "content is required"}), 400
             payload = {
-                "content": content,
-                "type": mem_type,
-                "concepts": concepts,
-                "files": files,
-                "project": project,
-                "agentId": agent_id
+                "content": content, "type": mem_type, "concepts": concepts,
+                "files": files, "project": project, "agentId": agent_id
             }
             res = functions.remember(kv, payload)
-            # If sessionId provided, write observation to link memory to session
-            if session_id and content:
-                obs_payload = {
-                    "sessionId": session_id,
-                    "project": project,
-                    "cwd": "",
-                    "hookType": "post_tool_use",
-                    "timestamp": datetime_now_iso(),
-                    "agentId": agent_id,
-                    "data": {
-                        "tool_name": "agent_remember",
-                        "tool_input": content[:500],
-                        "tool_output": res.get("id", ""),
-                    }
-                }
-                functions.observe(kv, obs_payload)
             text_out = json.dumps(res)
-            
-        elif name == "memory_antigravity_sync":
-            mode = args.get("mode") or "current_session"
-            current_convo = args.get("currentConversationId")
-            current_folder = args.get("currentFolder")
-            res = perform_antigravity_sync(mode, current_convo, current_folder)
-            text_out = json.dumps(res)
-            
-        elif name == "memory_antigravity_sync_all":
-            mode = args.get("mode") or "current_session"
-            current_convo = args.get("currentConversationId")
-            current_folder = args.get("currentFolder")
-            sync_res = perform_antigravity_sync(mode, current_convo, current_folder)
-            
-            synced_sessions = sync_res.get("syncedSessions") or []
-            crystallizations = {}
-            reflections = {}
-            
-            for cid in synced_sessions:
-                session_id = f"antigravity_{cid[:18].replace('-', '_')}"
-                
-                try:
-                    cres = functions.summarize(kv, {"sessionId": session_id})
-                    crystallizations[session_id] = cres
-                except Exception as ex:
-                    crystallizations[session_id] = {"success": False, "error": str(ex)}
-                    
-                try:
-                    rres = functions.slot_reflect(kv, session_id, 50)
-                    reflections[session_id] = rres
-                except Exception as ex:
-                    reflections[session_id] = {"success": False, "error": str(ex)}
-                    
-            text_out = json.dumps({
-                "success": sync_res.get("success", True),
-                "syncedSessions": synced_sessions,
-                "observationsAdded": sync_res.get("observationsAdded", 0),
-                "crystallizations": crystallizations,
-                "reflections": reflections
-            }, indent=2)
-            
-        elif name == "memory_slot_list":
-            res = functions.slot_list(kv)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_slot_get":
-            label = args.get("label")
-            if not label:
-                return jsonify({"error": "label is required"}), 400
-            res = functions.slot_get(kv, label)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_slot_create":
-            label = args.get("label")
-            if not label:
-                return jsonify({"error": "label is required"}), 400
-            res = functions.slot_create(kv, {
-                "label": label,
-                "content": args.get("content"),
-                "scope": args.get("scope") or "global",
-                "sizeLimit": args.get("sizeLimit"),
-                "pinned": args.get("pinned", True)
-            })
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_slot_append":
-            label = args.get("label")
-            text = args.get("text")
-            if not label or not text:
-                return jsonify({"error": "label and text are required"}), 400
-            res = functions.slot_append(kv, label, text)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_slot_replace":
-            label = args.get("label")
-            content = args.get("content")
-            if not label or content is None:
-                return jsonify({"error": "label and content are required"}), 400
-            res = functions.slot_replace(kv, label, content)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_slot_delete":
-            label = args.get("label")
-            if not label:
-                return jsonify({"error": "label is required"}), 400
-            res = functions.slot_delete(kv, label)
-            text_out = json.dumps(res, indent=2)
-            
-        elif name == "memory_action_create":
-            action_id = functions.generate_id("act")
-            from datetime import datetime, timezone
-            now = datetime.now(timezone.utc).isoformat()
-            tags = parse_mcp_list_arg(args.get("tags"))
-            action = {
-                "id": action_id,
-                "title": args.get("title") or "",
-                "description": args.get("description"),
-                "priority": args.get("priority", 0),
-                "status": args.get("status", "pending"),
-                "tags": tags,
-                "sessionId": args.get("sessionId"),
-                "createdAt": now,
-                "updatedAt": now,
-            }
-            kv.set(KV.actions, action_id, action)
-            text_out = json.dumps({"action": action, "success": True}, indent=2)
-            
-        elif name == "memory_action_update":
-            action_id = args.get("actionId")
-            if not action_id:
-                return jsonify({"error": "actionId is required"}), 400
-            existing = kv.get(KV.actions, action_id)
-            if not existing:
-                return jsonify({"error": "action not found"}), 404
-            from datetime import datetime, timezone
-            allowed_fields = {"title", "description", "priority", "status", "tags", "sessionId"}
-            updates = {k: v for k, v in args.items() if k in allowed_fields}
-            if "tags" in args:
-                updates["tags"] = parse_mcp_list_arg(args.get("tags"))
-            existing.update(updates)
-            existing["updatedAt"] = datetime.now(timezone.utc).isoformat()
-            kv.set(KV.actions, action_id, existing)
-            text_out = json.dumps({"action": existing, "success": True}, indent=2)
-            
-        elif name == "memory_frontier":
-            items = kv.list(KV.actions)
-            frontier = [a for a in items if a.get("status") in ("pending", "active")]
-            frontier.sort(key=lambda a: (-(a.get("priority") or 0), a.get("createdAt", "")))
-            text_out = json.dumps({"frontier": frontier[:50], "total": len(frontier)}, indent=2)
-            
-        elif name == "memory_crystallize":
-            session_id = args.get("sessionId")
-            if not session_id:
-                return jsonify({"error": "sessionId is required"}), 400
-            res = functions.summarize(kv, {"sessionId": session_id})
+
+        elif name == "memory_folders":
+            pairs = sorted(kv.list(functions.KV.folders), key=lambda x: x.get("lastUpdated", ""), reverse=True)
+            text_out = json.dumps(pairs, indent=2)
+
+        elif name == "memory_folder_observations":
+            fp = args.get("folderPath", "")
+            aid = args.get("agentId", "")
+            if not fp or not aid:
+                return jsonify({"error": "folderPath and agentId are required"}), 400
+            obs = sorted(kv.list(functions.KV.folder_obs(fp, aid)), key=lambda x: x.get("timestamp", ""), reverse=True)
+            text_out = json.dumps(obs, indent=2)
+
+        elif name == "memory_timeline":
+            res = functions.folder_timeline(
+                kv,
+                limit=int(args.get("limit", 100)),
+                folder_path=args.get("folderPath"),
+                agent_id=args.get("agentId"),
+                before=args.get("before"),
+                after=args.get("after"),
+            )
             text_out = json.dumps(res, indent=2)
             
         else:

src/functions.py

@@ -26,73 +26,66 @@ _hybrid_search = HybridSearch(_bm25_index, _vector_index, None, None)
 _index_persistence = None
 _stream_broadcaster = None  # Callable: (payload) -> None
 
-# Default scopes matching schema.ts
+# KV scope registry — folder-based memory model
 class KV:
-    sessions = "mem:sessions"
-    memories = "mem:memories"
-    summaries = "mem:summaries"
-    config = "mem:config"
-    metrics = "mem:metrics"
-    health = "mem:health"
-    bm25Index = "mem:index:bm25"
-    relations = "mem:relations"
-    profiles = "mem:profiles"
-    claudeBridge = "mem:claude-bridge"
-    graphNodes = "mem:graph:nodes"
-    graphEdges = "mem:graph:edges"
-    graphSnapshot = "mem:graph:snapshot"
-    graphNameIndex = "mem:graph:name-index"
-    graphEdgeKey = "mem:graph:edge-key"
-    graphNodeDegree = "mem:graph:node-degree"
-    semantic = "mem:semantic"
-    procedural = "mem:procedural"
-    audit = "mem:audit"
-    actions = "mem:actions"
-    actionEdges = "mem:action-edges"
-    leases = "mem:leases"
-    routines = "mem:routines"
-    routineRuns = "mem:routine-runs"
-    signals = "mem:signals"
-    checkpoints = "mem:checkpoints"
-    mesh = "mem:mesh"
-    sketches = "mem:sketches"
-    facets = "mem:facets"
-    sentinels = "mem:sentinels"
-    crystals = "mem:crystals"
-    lessons = "mem:lessons"
-    insights = "mem:insights"
-    graphEdgeHistory = "mem:graph:edge-history"
-    retentionScores = "mem:retention"
-    accessLog = "mem:access"
-    imageRefs = "mem:image-refs"
-    slots = "mem:slots"
-    globalSlots = "mem:slots:global"
-    commits = "mem:commits"
-    recentSearches = "mem:recent-searches"
+    # ---- Folder memory scopes (new) ----
 
-    @staticmethod
-    def observations(session_id: str) -> str:
-        return f"mem:obs:{session_id}"
+    # Global index of all (folder_path, agent_id) pairs known to the system.
+    # Key = "{safe_folder_path}:{agent_id}", value = FolderIndexEntry dict.
+    folders = "mem:folders"
 
     @staticmethod
-    def team_shared(team_id: str) -> str:
-        return f"mem:team:{team_id}:shared"
+    def folder_obs(folder_path: str, agent_id: str) -> str:
+        """Per-(folder, agent) observations scope.
+        Key = obs_id, value = FolderObservation dict.
+        """
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:folder:{safe_path}:{safe_agent}"
 
     @staticmethod
-    def team_users(team_id: str, user_id: str) -> str:
-        return f"mem:team:{team_id}:users:{user_id}"
+    def folder_meta(folder_path: str, agent_id: str) -> str:
+        """Per-(folder, agent) metadata scope.
+        Key = "meta", value = FolderMeta dict (obsCount, lastUpdated, summary).
+        """
+        safe_path = folder_path.replace("\\", "/").strip("/")
+        safe_agent = agent_id.strip()
+        return f"mem:foldermeta:{safe_path}:{safe_agent}"
 
-    @staticmethod
-    def team_profile(team_id: str) -> str:
-        return f"mem:team:{team_id}:profile"
+    # ---- Global / shared scopes (kept) ----
 
-    @staticmethod
-    def enriched_chunks(session_id: str) -> str:
-        return f"mem:enriched:{session_id}"
+    # Long-term memories — unchanged from previous implementation.
+    memories = "mem:memories"
 
-    @staticmethod
-    def latent_embeddings(obs_id: str) -> str:
-        return f"mem:latent:{obs_id}"
+    # BM25 index shards — unchanged.
+    bm25Index = "mem:index:bm25"
+
+    # Audit log — unchanged.
+    audit = "mem:audit"
+
+    # Graph edges — repurposed for folder graph edges.
+    relations = "mem:relations"
+
+def get_current_project(kv: StateKV) -> Optional[str]:
+    try:
+        sessions = kv.list(KV.sessions)
+        if not sessions:
+            return None
+        active_sessions = [s for s in sessions if s.get("status") == "active"]
+        if active_sessions:
+            active_sessions.sort(key=lambda s: s.get("updatedAt", ""), reverse=True)
+            return active_sessions[0].get("project")
+        sessions.sort(key=lambda s: s.get("updatedAt", ""), reverse=True)
+        return sessions[0].get("project")
+    except Exception:
+        return None
+
+def project_slots_scope(kv: StateKV, project: Optional[str] = None) -> str:
+    if not project:
+        project = get_current_project(kv)
+    if not project:
+        return KV.slots
+    return f"mem:slots:{project}"
 
 # =====================================================================
 # Core Helpers & Utilities
@@ -114,12 +107,96 @@ def fingerprint_id(prefix: str, content: str) -> str:
     h = hashlib.sha256(content.strip().lower().encode('utf-8')).hexdigest()
     return f"{prefix}_{h[:16]}"
 
-def auto_complete_old_active_sessions(kv: StateKV, current_session_id: str) -> int:
+# ---- Folder-path normalisation (REQ-002, REQ-063, REQ-064, REQ-066) ----
+
+_MAX_PATH_LEN = 512
+
+
+def normalize_folder_path(path: str) -> str:
+    """Normalize a folder path for safe use in KV scope keys.
+
+    Steps applied in order:
+    1. Cap the raw input at 512 characters (REQ-066).
+    2. Apply ``os.path.normpath`` to collapse redundant separators and
+       resolve any ``..`` components at the OS level.
+    3. Convert all OS-native separators to forward slashes.
+    4. Strip any remaining leading or trailing slashes.
+
+    Raises:
+        ValueError: if *path* is empty (before or after normalization), or
+                    if the normalized result still contains a ``..`` segment,
+                    which would indicate an attempt at path traversal
+                    (REQ-064).
+
+    Returns:
+        A non-empty, forward-slash-separated string with no leading/trailing
+        slashes and no ``..`` segments — safe for use as a KV scope fragment.
+
+    Property (REQ-074): idempotent — applying this function twice yields
+    the same result as applying it once.
+    """
+    if not path:
+        raise ValueError("folder_path must not be empty")
+
+    # 1. Length cap before any processing.
+    path = path[:_MAX_PATH_LEN]
+
+    # 2. OS-level normalisation (resolves .., duplicate separators, etc.)
+    normalized = os.path.normpath(path)
+
+    # 3. Unify separators to forward slash.
+    normalized = normalized.replace("\\", "/")
+
+    # 4. Strip leading / trailing slashes.
+    normalized = normalized.strip("/")
+
+    # Guard: reject path traversal patterns that survive normalisation.
+    # Split on "/" and check each component; normpath should have already
+    # resolved most cases but we verify explicitly for safety.
+    parts = normalized.split("/")
+    if any(part == ".." for part in parts):
+        raise ValueError(
+            f"folder_path contains path traversal segment '..': {path!r}"
+        )
+
+    if not normalized:
+        raise ValueError("folder_path is empty after normalization")
+
+    return normalized
+
+
+def validate_agent_id(agent_id: str) -> str:
+    """Validate and sanitize an agent_id before use in KV scope keys.
+
+    Strips surrounding whitespace and caps at 512 characters (REQ-066).
+
+    Raises:
+        ValueError: if *agent_id* is empty after stripping.
+
+    Returns:
+        Sanitized agent_id string.
+    """
+    if not agent_id:
+        raise ValueError("agent_id must not be empty")
+
+    sanitized = agent_id.strip()[:_MAX_PATH_LEN]
+
+    if not sanitized:
+        raise ValueError("agent_id is empty after stripping whitespace")
+
+    return sanitized
+
+
+def auto_complete_old_active_sessions(kv: StateKV, current_session_id: str, project: Optional[str] = None, agent_id: Optional[str] = None) -> int:
     sessions = kv.list(KV.sessions)
     count = 0
     now = datetime.datetime.utcnow().isoformat() + "Z"
     for s in sessions:
         if s.get("id") != current_session_id and s.get("status") == "active":
+            if project and s.get("project") != project:
+                continue
+            if agent_id and s.get("agentId") != agent_id:
+                continue
             s["status"] = "completed"
             if "endedAt" not in s:
                 s["endedAt"] = now
@@ -406,9 +483,10 @@ class IndexPersistence:
         try:
             conn = self.kv._get_conn()
             try:
-                with conn.cursor() as cursor:
+                cursor = conn.cursor()
+                try:
                     cursor.execute(
-                        "SELECT DISTINCT scope FROM kv_store WHERE scope LIKE %s",
+                        "SELECT DISTINCT scope FROM kv_store WHERE scope LIKE ?",
                         (scope_prefix + "%",)
                     )
                     rows = cursor.fetchall()
@@ -422,11 +500,14 @@ class IndexPersistence:
                     if to_delete:
                         for i in range(0, len(to_delete), 50):
                             chunk_delete = to_delete[i:i + 50]
-                            format_strings = ','.join(['%s'] * len(chunk_delete))
+                            format_strings = ','.join(['?'] * len(chunk_delete))
                             cursor.execute(
                                 f"DELETE FROM kv_store WHERE scope IN ({format_strings})",
                                 tuple(chunk_delete)
                             )
+                            conn.commit()
+                finally:
+                    cursor.close()
             finally:
                 conn.close()
         except Exception as ex:
@@ -696,7 +777,8 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
     max_obs = int(os.getenv("MAX_OBS_PER_SESSION", "500"))
     if max_obs > 0:
         existing = kv.list(KV.observations(session_id))
-        if len(existing) >= max_obs:
+        actual_obs_count = sum(1 for o in existing if not str(o.get("id", "")).endswith(":raw"))
+        if actual_obs_count >= max_obs:
             raise ValueError(f"Session observation limit reached ({max_obs})")
 
     existing_session = kv.get(KV.sessions, session_id)
@@ -716,7 +798,8 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
             print(f"[image store] failed: {ex}")
 
     # Set raw observation
-    kv.set(KV.observations(session_id), obs_id, raw)
+    raw["id"] = f"{obs_id}:raw"
+    kv.set(KV.observations(session_id), raw["id"], raw)
 
     # Stream raw observation
     broadcast_stream({
@@ -740,8 +823,8 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
                 updates.append({"type": "set", "path": "firstPrompt", "value": trimmed[:200]})
         kv.update(KV.sessions, session_id, updates)
     else:
-        auto_complete_old_active_sessions(kv, session_id)
         project = payload.get("project") or "unknown"
+        auto_complete_old_active_sessions(kv, session_id, project=project, agent_id=inherited_agent_id)
         cwd = payload.get("cwd") or os.getcwd()
         trimmed_prompt = None
         if isinstance(raw.get("userPrompt"), str):
@@ -763,10 +846,12 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
         kv.set(KV.sessions, session_id, new_sess)
 
     # Perform synthetic compression (we default to synthetic)
-    synthetic = build_synthetic_compression(raw)
+    raw_for_synthetic = dict(raw)
+    raw_for_synthetic["id"] = obs_id
+    synthetic = build_synthetic_compression(raw_for_synthetic)
     for k in ["hookType", "raw", "toolName", "toolInput", "toolOutput", "userPrompt"]:
-        if k in raw:
-            synthetic[k] = raw[k]
+        if k in raw_for_synthetic:
+            synthetic[k] = raw_for_synthetic[k]
     kv.set(KV.observations(session_id), obs_id, synthetic)
     _bm25_index.add(synthetic)
 
@@ -793,6 +878,333 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
     return {"observationId": obs_id}
 
 
+# =====================================================================
+# Folder-Based Observation Ingestion (folder_observe)
+# =====================================================================
+
+def folder_observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Ingest a new observation scoped to a (folder_path, agent_id) pair.
+
+    Required payload fields:
+        folderPath: str      — absolute path of working directory
+        agentId: str         — identity of the agent making the observation
+        text: str            — human-readable observation content
+        timestamp: str       — ISO 8601 UTC
+
+    Optional payload fields:
+        type: str            — observation type (default inferred or "other")
+        title: str           — short title (auto-generated from text[:80] if absent)
+        concepts: list[str]  — concept tags (default [])
+        files: list[str]     — referenced file paths (default [] or extracted)
+        importance: int      — 1-10 (default 5, clamped)
+
+    Returns: {"observationId": str}
+    Raises:  ValueError if required fields are missing or folder cap exceeded.
+    """
+    # 1. Validate required fields (REQ-008)
+    folder_path_raw = payload.get("folderPath")
+    agent_id_raw = payload.get("agentId")
+    text_raw = payload.get("text")
+    timestamp = payload.get("timestamp")
+
+    if not folder_path_raw:
+        raise ValueError("Invalid payload: folderPath is required")
+    if not agent_id_raw:
+        raise ValueError("Invalid payload: agentId is required")
+    if not text_raw:
+        raise ValueError("Invalid payload: text is required")
+    if not timestamp:
+        raise ValueError("Invalid payload: timestamp is required")
+
+    # 2. Normalize folder_path and validate agent_id (REQ-002, REQ-063, REQ-064, REQ-066)
+    folder_path = normalize_folder_path(folder_path_raw)
+    agent_id = validate_agent_id(agent_id_raw)
+
+    # 3. Strip private data and cap text (REQ-009, REQ-007)
+    safe_text = strip_private_data(text_raw)
+    safe_text = safe_text[:4000]
+
+    # 10. Enforce MAX_OBS_PER_FOLDER cap before writing (REQ-015)
+    max_obs = int(os.getenv("MAX_OBS_PER_FOLDER", "2000"))
+    if max_obs > 0:
+        existing_obs = kv.list(KV.folder_obs(folder_path, agent_id))
+        if len(existing_obs) >= max_obs:
+            raise ValueError(f"Folder observation limit reached ({max_obs})")
+
+    # 4. Generate obs_id (REQ-010)
+    obs_id = generate_id("fobs")
+
+    # 5. Determine optional fields
+    obs_type = payload.get("type")
+    if not obs_type:
+        # Use infer_type with no tool_name; pass "other" as hook_type
+        obs_type = infer_type(None, "other")
+
+    title = payload.get("title")
+    if not title:
+        title = safe_text[:80]
+
+    concepts = payload.get("concepts") or []
+    if not isinstance(concepts, list):
+        concepts = []
+
+    files = payload.get("files")
+    if not isinstance(files, list):
+        # Try to extract file refs from the payload itself
+        files = extract_files(payload)
+
+    raw_importance = payload.get("importance")
+    if raw_importance is None:
+        importance = 5
+    else:
+        try:
+            importance = max(1, min(10, int(raw_importance)))
+        except (TypeError, ValueError):
+            importance = 5
+
+    # 5. Build FolderObservation dict (REQ-003)
+    obs: Dict[str, Any] = {
+        "id": obs_id,
+        "folderPath": folder_path,
+        "agentId": agent_id,
+        "timestamp": timestamp,
+        "text": safe_text,
+        "type": obs_type,
+        "title": title,
+        "concepts": concepts,
+        "files": files,
+        "importance": importance,
+    }
+
+    # 6. Write observation to KV (REQ-001)
+    obs_scope = KV.folder_obs(folder_path, agent_id)
+    kv.set(obs_scope, obs_id, obs)
+
+    # 7. Upsert folder metadata (REQ-005)
+    meta_scope = KV.folder_meta(folder_path, agent_id)
+    meta = kv.get(meta_scope, "meta") or {
+        "folderPath": folder_path,
+        "agentId": agent_id,
+        "obsCount": 0,
+        "lastUpdated": timestamp,
+        "summary": None,
+    }
+    meta["obsCount"] = meta.get("obsCount", 0) + 1
+    meta["lastUpdated"] = timestamp
+    kv.set(meta_scope, "meta", meta)
+
+    # 8. Upsert global folders index entry (REQ-004, REQ-011)
+    index_key = f"{folder_path}:{agent_id}"
+    kv.set(KV.folders, index_key, {
+        "folderPath": folder_path,
+        "agentId": agent_id,
+        "lastUpdated": meta["lastUpdated"],
+        "obsCount": meta["obsCount"],
+    })
+
+    # 9. Add to BM25 index and vector index (REQ-012)
+    try:
+        _bm25_index.add(obs)
+    except Exception as ex:
+        print(f"[bm25] folder_observe add failed: {ex}")
+
+    comb_text = title + " " + safe_text
+    vector_index_add_guarded(obs_id, folder_path, comb_text, {"kind": "folder_obs", "logId": obs_id})
+
+    if _index_persistence:
+        _index_persistence.schedule_save()
+
+    # 11. Write audit log entry (REQ-014)
+    kv.commit_version(f"folder_observe: {obs_id}", agent_id)
+
+    # 12. Broadcast via WebSocket stream (REQ-013)
+    broadcast_stream({
+        "type": "folder_observation",
+        "folderPath": folder_path,
+        "agentId": agent_id,
+        "data": obs,
+    })
+
+    return {"observationId": obs_id}
+
+
+# =====================================================================
+# Folder-Based Search (folder_search)
+# =====================================================================
+
+def folder_search(
+    kv: StateKV,
+    query: str,
+    limit: int = 20,
+    folder_path: Optional[str] = None,
+    agent_id: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Search across all folder observations (and global memories) using BM25 + vector hybrid search.
+
+    Steps:
+    1. Run hybrid search to obtain up to ``limit * 2`` candidate obs_ids with scores.
+    2. Hydrate each candidate by looking up the observation in the KV store:
+       - Iterate ``KV.folders`` index to discover all (folder_path, agent_id) pairs.
+       - For each pair, load observations from ``KV.folder_obs`` and build an obs_id → obs map.
+    3. Apply ``folder_path`` and ``agent_id`` post-filters to folder observations.
+    4. Also include matching global memories from ``KV.memories``.
+    5. Return results sorted by score descending, capped at ``limit``.
+
+    Each result dict contains at minimum: ``folderPath``, ``agentId``, ``score``,
+    plus all fields from the underlying FolderObservation or Memory object.
+
+    Requirements: REQ-016, REQ-017, REQ-018, REQ-019
+    """
+    if not query or not query.strip():
+        return []
+
+    candidates = _hybrid_search.search(query, limit * 2)
+
+    # --- Build a comprehensive obs_id → observation mapping from all folder pairs ---
+    # First, collect all known (folder_path, agent_id) pairs from the folders index.
+    index_entries = kv.list(KV.folders)
+
+    obs_map: Dict[str, Dict[str, Any]] = {}  # obs_id → observation dict
+
+    for entry in index_entries:
+        fp = entry.get("folderPath", "")
+        aid = entry.get("agentId", "")
+        if not fp or not aid:
+            continue
+
+        # Apply early filter: skip pairs that don't match the requested filters
+        if folder_path is not None and fp != folder_path:
+            continue
+        if agent_id is not None and aid != agent_id:
+            continue
+
+        obs_scope = KV.folder_obs(fp, aid)
+        pair_obs_list = kv.list(obs_scope)
+        for obs in pair_obs_list:
+            oid = obs.get("id")
+            if oid:
+                obs_map[oid] = obs
+
+    # --- Also build a memory map from KV.memories for cross-inclusion (REQ-018) ---
+    # We include memories regardless of folder/agent filters since they are global.
+    all_memories = kv.list(KV.memories)
+    memory_map: Dict[str, Dict[str, Any]] = {}
+    for mem in all_memories:
+        mid = mem.get("id")
+        if mid:
+            memory_map[mid] = mem
+
+    # --- Hydrate candidates from the search results ---
+    results: List[Dict[str, Any]] = []
+    seen_ids: set = set()
+
+    for candidate in candidates:
+        obs_id = candidate.get("obsId") or candidate.get("id", "")
+        score = candidate.get("combinedScore") or candidate.get("score", 0.0)
+
+        if obs_id in seen_ids:
+            continue
+
+        # Try folder observation first
+        obs = obs_map.get(obs_id)
+        if obs is not None:
+            result = dict(obs)
+            result["score"] = score
+            # Ensure folderPath and agentId are present (REQ-019)
+            result.setdefault("folderPath", obs.get("folderPath", ""))
+            result.setdefault("agentId", obs.get("agentId", ""))
+            results.append(result)
+            seen_ids.add(obs_id)
+            continue
+
+        # Try global memory (REQ-018)
+        mem = memory_map.get(obs_id)
+        if mem is not None:
+            result = dict(mem)
+            result["score"] = score
+            # Global memories have no folder scope; use empty strings as sentinels
+            result.setdefault("folderPath", "")
+            result.setdefault("agentId", mem.get("agentId") or "")
+            results.append(result)
+            seen_ids.add(obs_id)
+            continue
+
+        # obs_id not found in either map — skip (stale index entry)
+
+    # Sort by score descending and cap at limit (REQ-016)
+    results.sort(key=lambda r: r.get("score", 0.0), reverse=True)
+    return results[:limit]
+
+
+def folder_timeline(
+    kv: StateKV,
+    limit: int = 100,
+    folder_path: Optional[str] = None,
+    agent_id: Optional[str] = None,
+    before: Optional[str] = None,
+    after: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Return a folder activity feed — observations sorted by timestamp descending.
+
+    Algorithm:
+    1. List all (folder, agent) pairs from ``KV.folders``.
+    2. Apply ``folder_path`` exact-match filter if provided.
+    3. Apply ``agent_id`` exact-match filter if provided.
+    4. For each remaining pair, load all observations from
+       ``KV.folder_obs(entry["folderPath"], entry["agentId"])``.
+    5. Apply ``before`` ISO timestamp upper-bound filter:
+       exclude obs where ``obs["timestamp"] >= before``.
+    6. Apply ``after`` ISO timestamp lower-bound filter:
+       exclude obs where ``obs["timestamp"] <= after``.
+    7. Sort all collected observations by ``timestamp`` descending.
+    8. Return the first ``limit`` entries.
+
+    Postconditions (REQ-071):
+    - ``len(result) <= limit``
+    - All results satisfy the provided filter conditions.
+    - Results are in non-increasing timestamp order.
+
+    Requirements: REQ-020, REQ-021, REQ-022
+    """
+    # Step 1 — load the global folders index
+    index_entries = kv.list(KV.folders)
+
+    # Step 2 — filter by folder_path exact match (REQ-021)
+    if folder_path is not None:
+        index_entries = [e for e in index_entries if e.get("folderPath") == folder_path]
+
+    # Step 3 — filter by agent_id exact match (REQ-021)
+    if agent_id is not None:
+        index_entries = [e for e in index_entries if e.get("agentId") == agent_id]
+
+    all_obs: List[Dict[str, Any]] = []
+
+    for entry in index_entries:
+        fp = entry.get("folderPath", "")
+        aid = entry.get("agentId", "")
+        if not fp or not aid:
+            continue
+
+        # Step 4 — load observations for this pair
+        obs_scope = KV.folder_obs(fp, aid)
+        obs_list = kv.list(obs_scope)
+
+        # Step 5 — apply before filter: exclude obs where timestamp >= before (REQ-021)
+        if before is not None:
+            obs_list = [o for o in obs_list if o.get("timestamp", "") < before]
+
+        # Step 6 — apply after filter: exclude obs where timestamp <= after (REQ-021)
+        if after is not None:
+            obs_list = [o for o in obs_list if o.get("timestamp", "") > after]
+
+        all_obs.extend(obs_list)
+
+    # Step 7 — sort by timestamp descending (REQ-071)
+    all_obs.sort(key=lambda o: o.get("timestamp", ""), reverse=True)
+
+    # Step 8 — return at most limit entries (REQ-022)
+    return all_obs[:limit]
+
 # =====================================================================
 # Memory System (Remember, Forget, Evolve)
 # =====================================================================
@@ -896,14 +1308,33 @@ def remember(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def forget(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
+    """Delete a global memory, a folder (folder_path+agent_id), or specific observations.
+
+    Dispatch rules (REQ-029, REQ-030, REQ-031, REQ-032, REQ-033):
+      1. ``memoryId`` present              → delete that global memory from KV.memories
+      2. ``folderPath + agentId`` present,
+         no ``observationIds``             → delete ALL observations for that pair,
+                                             remove BM25 entries, delete folder_meta,
+                                             remove from KV.folders index
+      3. ``folderPath + agentId +
+         observationIds`` present          → delete only the listed observations,
+                                             decrement obsCount in metadata
+
+    Legacy session-based paths are preserved for backward compatibility.
+    """
     memory_id = data.get("memoryId")
     session_id = data.get("sessionId")
+    folder_path_raw = data.get("folderPath")
+    agent_id_raw = data.get("agentId")
     obs_ids = data.get("observationIds") or []
     deleted = 0
     deleted_mem_ids = []
     deleted_obs_ids = []
     deleted_session = False
 
+    # ------------------------------------------------------------------
+    # Path 1: delete a global memory (REQ-029)
+    # ------------------------------------------------------------------
     if memory_id:
         mem = kv.get(KV.memories, memory_id)
         kv.delete(KV.memories, memory_id)
@@ -918,23 +1349,97 @@ def forget(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         deleted_mem_ids.append(memory_id)
         deleted += 1
 
+    # ------------------------------------------------------------------
+    # Path 2 & 3: folder-based deletion (REQ-030, REQ-031, REQ-032, REQ-033)
+    # ------------------------------------------------------------------
+    if folder_path_raw and agent_id_raw:
+        try:
+            fp = normalize_folder_path(folder_path_raw)
+            aid = validate_agent_id(agent_id_raw)
+        except ValueError as exc:
+            return {"success": False, "error": str(exc), "deleted": 0}
+
+        obs_scope = KV.folder_obs(fp, aid)
+        meta_scope = KV.folder_meta(fp, aid)
+        index_key = f"{fp}:{aid}"
+
+        if obs_ids:
+            # ----------------------------------------------------------
+            # Path 3: partial deletion — only the listed obs IDs (REQ-031)
+            # ----------------------------------------------------------
+            partial_deleted = 0
+            for oid in obs_ids:
+                existed = kv.delete(obs_scope, oid)
+                if existed:
+                    _bm25_index.remove(oid)
+                    if _vector_index:
+                        _vector_index.remove(oid)
+                    deleted_obs_ids.append(oid)
+                    partial_deleted += 1
+                    deleted += 1
+
+            # Decrement obsCount in metadata
+            if partial_deleted > 0:
+                meta = kv.get(meta_scope, "meta")
+                if meta and isinstance(meta, dict):
+                    current_count = meta.get("obsCount", 0)
+                    meta["obsCount"] = max(0, current_count - partial_deleted)
+                    kv.set(meta_scope, "meta", meta)
+                    # Also sync the folders index entry
+                    index_entry = kv.get(KV.folders, index_key)
+                    if index_entry and isinstance(index_entry, dict):
+                        index_entry["obsCount"] = meta["obsCount"]
+                        kv.set(KV.folders, index_key, index_entry)
+        else:
+            # ----------------------------------------------------------
+            # Path 2: full pair deletion (REQ-030, REQ-032)
+            # ----------------------------------------------------------
+            all_obs = kv.list(obs_scope)
+            for obs in all_obs:
+                obs_id = obs.get("id")
+                if obs_id:
+                    kv.delete(obs_scope, obs_id)
+                    _bm25_index.remove(obs_id)
+                    if _vector_index:
+                        _vector_index.remove(obs_id)
+                    deleted_obs_ids.append(obs_id)
+                    deleted += 1
+
+            # Delete folder metadata entry
+            kv.delete(meta_scope, "meta")
+
+            # Remove from global folders index
+            kv.delete(KV.folders, index_key)
+
+    # ------------------------------------------------------------------
+    # Legacy: session-based deletion (unchanged)
+    # ------------------------------------------------------------------
     if session_id and obs_ids:
         for oid in obs_ids:
-            obs = kv.get(KV.observations(session_id), oid)
-            kv.delete(KV.observations(session_id), oid)
-            if obs:
-                img = obs.get("imageData") or obs.get("imageRef")
-                if img:
-                    refs = kv.get(KV.imageRefs, img) or 0
-                    if refs > 0:
-                        kv.set(KV.imageRefs, img, refs - 1)
-            _bm25_index.remove(oid)
+            base_oid = oid.replace(":raw", "")
+            obs = kv.get(KV.observations(session_id), base_oid)
+            raw_obs = kv.get(KV.observations(session_id), f"{base_oid}:raw")
+
+            kv.delete(KV.observations(session_id), base_oid)
+            kv.delete(KV.observations(session_id), f"{base_oid}:raw")
+
+            for o in (obs, raw_obs):
+                if o:
+                    img = o.get("imageData") or o.get("imageRef")
+                    if img:
+                        refs = kv.get(KV.imageRefs, img) or 0
+                        if refs > 0:
+                            kv.set(KV.imageRefs, img, refs - 1)
+
+            _bm25_index.remove(base_oid)
+            _bm25_index.remove(f"{base_oid}:raw")
             if _vector_index:
-                _vector_index.remove(oid)
+                _vector_index.remove(base_oid)
+                _vector_index.remove(f"{base_oid}:raw")
             deleted_obs_ids.append(oid)
             deleted += 1
 
-    if session_id and not obs_ids and not memory_id:
+    if session_id and not obs_ids and not memory_id and not folder_path_raw:
         obs_list = kv.list(KV.observations(session_id))
         for obs in obs_list:
             kv.delete(KV.observations(session_id), obs["id"])
@@ -962,7 +1467,10 @@ def forget(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
             "mem::forget",
             deleted_mem_ids + deleted_obs_ids,
             {
+                "memoryId": memory_id,
                 "sessionId": session_id,
+                "folderPath": folder_path_raw,
+                "agentId": agent_id_raw,
                 "deleted": deleted,
                 "memoriesDeleted": len(deleted_mem_ids),
                 "observationsDeleted": len(deleted_obs_ids),
@@ -970,10 +1478,9 @@ def forget(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
                 "reason": "user-initiated forget"
             }
         )
-        
-        # Commit to Dolt
+
         agent_id = data.get("agentId") or get_agent_id()
-        commit_if_enabled(kv, f"Forget: memory_id={memory_id} session_id={session_id}", agent_id)
+        commit_if_enabled(kv, f"Forget: memory_id={memory_id} folder_path={folder_path_raw}", agent_id)
 
     return {"success": True, "deleted": deleted}
 
@@ -999,7 +1506,7 @@ def context(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     blocks = []
 
     # 1. Pinned Slots
-    pinned_slots = list_pinned_slots(kv)
+    pinned_slots = list_pinned_slots(kv, project)
     slot_content = render_pinned_context(pinned_slots)
     if slot_content:
         blocks.append({
@@ -1212,8 +1719,8 @@ def seed_defaults(kv: StateKV) -> None:
         slot["updatedAt"] = now
         kv.set(target, tmpl["label"], slot)
 
-def list_pinned_slots(kv: StateKV) -> List[Dict[str, Any]]:
-    p_slots = kv.list(KV.slots)
+def list_pinned_slots(kv: StateKV, project: Optional[str] = None) -> List[Dict[str, Any]]:
+    p_slots = kv.list(project_slots_scope(kv, project))
     g_slots = kv.list(KV.globalSlots)
     merged = {}
     for s in g_slots:
@@ -1234,8 +1741,8 @@ def render_pinned_context(slots: List[Dict[str, Any]]) -> str:
         lines.append("")
     return "\n".join(lines)
 
-def slot_list(kv: StateKV) -> Dict[str, Any]:
-    p_slots = kv.list(KV.slots)
+def slot_list(kv: StateKV, project: Optional[str] = None) -> Dict[str, Any]:
+    p_slots = kv.list(project_slots_scope(kv, project))
     g_slots = kv.list(KV.globalSlots)
     merged = {}
     for s in g_slots:
@@ -1245,10 +1752,11 @@ def slot_list(kv: StateKV) -> Dict[str, Any]:
     slots = sorted(list(merged.values()), key=lambda s: s["label"])
     return {"success": True, "slots": slots}
 
-def slot_get(kv: StateKV, label: str) -> Dict[str, Any]:
-    project = kv.get(KV.slots, label)
-    if project:
-        return {"success": True, "slot": project, "scope": "project"}
+def slot_get(kv: StateKV, label: str, project: Optional[str] = None) -> Dict[str, Any]:
+    p_scope = project_slots_scope(kv, project)
+    project_s = kv.get(p_scope, label)
+    if project_s:
+        return {"success": True, "slot": project_s, "scope": "project"}
     global_s = kv.get(KV.globalSlots, label)
     if global_s:
         return {"success": True, "slot": global_s, "scope": "global"}
@@ -1273,8 +1781,9 @@ def slot_create(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
     description = data.get("description") or ""
     pinned = data.get("pinned", True)
+    project = data.get("project")
 
-    target_kv = KV.globalSlots if scope == "global" else KV.slots
+    target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
     existing = kv.get(target_kv, label)
     if existing:
         return {"success": False, "error": f"slot already exists in {scope} scope"}
@@ -1300,14 +1809,14 @@ def slot_create(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
     return {"success": True, "slot": slot}
 
-def slot_append(kv: StateKV, label: str, text: str, agent_id: Optional[str] = None) -> Dict[str, Any]:
-    res = slot_get(kv, label)
+def slot_append(kv: StateKV, label: str, text: str, agent_id: Optional[str] = None, project: Optional[str] = None) -> Dict[str, Any]:
+    res = slot_get(kv, label, project)
     if not res.get("success"):
         return {"success": False, "error": "slot not found"}
 
     slot = res["slot"]
     scope = res["scope"]
-    target_kv = KV.globalSlots if scope == "global" else KV.slots
+    target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
 
     if slot.get("readOnly"):
         return {"success": False, "error": "slot is read-only"}
@@ -1336,14 +1845,14 @@ def slot_append(kv: StateKV, label: str, text: str, agent_id: Optional[str] = No
 
     return {"success": True, "slot": slot, "size": len(next_content)}
 
-def slot_replace(kv: StateKV, label: str, content: str, agent_id: Optional[str] = None) -> Dict[str, Any]:
-    res = slot_get(kv, label)
+def slot_replace(kv: StateKV, label: str, content: str, agent_id: Optional[str] = None, project: Optional[str] = None) -> Dict[str, Any]:
+    res = slot_get(kv, label, project)
     if not res.get("success"):
         return {"success": False, "error": "slot not found"}
 
     slot = res["slot"]
     scope = res["scope"]
-    target_kv = KV.globalSlots if scope == "global" else KV.slots
+    target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
 
     if slot.get("readOnly"):
         return {"success": False, "error": "slot is read-only"}
@@ -1369,14 +1878,14 @@ def slot_replace(kv: StateKV, label: str, content: str, agent_id: Optional[str]
 
     return {"success": True, "slot": slot, "size": len(content)}
 
-def slot_delete(kv: StateKV, label: str, agent_id: Optional[str] = None) -> Dict[str, Any]:
-    res = slot_get(kv, label)
+def slot_delete(kv: StateKV, label: str, agent_id: Optional[str] = None, project: Optional[str] = None) -> Dict[str, Any]:
+    res = slot_get(kv, label, project)
     if not res.get("success"):
         return {"success": False, "error": "slot not found"}
 
     slot = res["slot"]
     scope = res["scope"]
-    target_kv = KV.globalSlots if scope == "global" else KV.slots
+    target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
 
     if slot.get("readOnly"):
         return {"success": False, "error": "slot is read-only"}
@@ -1391,6 +1900,9 @@ def slot_delete(kv: StateKV, label: str, agent_id: Optional[str] = None) -> Dict
 
 
 def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, Any]:
+    session = kv.get(KV.sessions, session_id)
+    project = session.get("project") if session else None
+
     observations = kv.list(KV.observations(session_id))
     if not observations:
         return {"success": True, "applied": 0, "reason": "no observations for session"}
@@ -1417,11 +1929,11 @@ def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, A
     now = datetime.datetime.utcnow().isoformat() + "Z"
 
     if pending_lines:
-        res = slot_get(kv, "pending_items")
+        res = slot_get(kv, "pending_items", project)
         if res.get("success"):
             slot = res["slot"]
             scope = res["scope"]
-            target_kv = scopeKv = KV.globalSlots if scope == "global" else KV.slots
+            target_kv = scopeKv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
             already = set((slot.get("content") or "").split("\n"))
             fresh = [l for l in pending_lines if l not in already]
             if fresh:
@@ -1436,11 +1948,11 @@ def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, A
                 applied += 1
 
     if pattern_counts:
-        res = slot_get(kv, "session_patterns")
+        res = slot_get(kv, "session_patterns", project)
         if res.get("success"):
             slot = res["slot"]
             scope = res["scope"]
-            target_kv = KV.globalSlots if scope == "global" else KV.slots
+            target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
             summary = [f"last reflection: {now}"]
             for k, v in pattern_counts.items():
                 summary.append(f"- {k}: {v} in last {len(recent)} observations")
@@ -1454,11 +1966,11 @@ def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, A
             applied += 1
 
     if files:
-        res = slot_get(kv, "project_context")
+        res = slot_get(kv, "project_context", project)
         if res.get("success"):
             slot = res["slot"]
             scope = res["scope"]
-            target_kv = KV.globalSlots if scope == "global" else KV.slots
+            target_kv = KV.globalSlots if scope == "global" else project_slots_scope(kv, project)
             already = slot.get("content") or ""
             fresh = [f for f in files if f not in already][:20]
             if fresh:
@@ -1685,24 +2197,46 @@ def rebuild_index(kv: StateKV) -> int:
     if _vector_index:
         _vector_index.clear()
 
-    # Backfill BM25 with observations
-    sessions = kv.list(KV.sessions)
     total_indexed = 0
 
-    for sess in sessions:
-        sid = sess.get("id")
-        if not sid:
+    # ---- Path A: folder-based observations (new schema) ----
+    folder_pairs = kv.list(KV.folders)
+    for entry in folder_pairs:
+        fp = entry.get("folderPath")
+        aid = entry.get("agentId")
+        if not fp or not aid:
             continue
-        obs_list = kv.list(KV.observations(sid))
+        obs_list = kv.list(KV.folder_obs(fp, aid))
         for obs in obs_list:
-            # Only index compressed (non-raw) observations
-            if obs.get("title") and obs.get("narrative"):
-                _bm25_index.add(obs)
-                comb_text = obs["title"] + " " + obs["narrative"]
-                vector_index_add_guarded(obs["id"], sid, comb_text, {"kind": "observation", "logId": obs["id"]})
-                total_indexed += 1
-
-    # Backfill BM25 with memories
+            if not obs.get("id"):
+                continue
+            _bm25_index.add(obs)
+            comb_text = (obs.get("title") or "") + " " + (obs.get("text") or "")
+            vector_index_add_guarded(obs["id"], fp, comb_text.strip(), {"kind": "folder_observation", "logId": obs["id"]})
+            total_indexed += 1
+
+    # ---- Path B: session-based observations (legacy schema — kept for old data) ----
+    try:
+        sessions = kv.list(KV.sessions)
+        for sess in sessions:
+            sid = sess.get("id")
+            if not sid:
+                continue
+            obs_list = kv.list(KV.observations(sid))
+            for obs in obs_list:
+                # Only index compressed (non-raw) observations
+                if obs.get("title") and obs.get("narrative"):
+                    # Skip if already indexed via folder path (same obs id)
+                    if _bm25_index.has(obs["id"]):
+                        continue
+                    _bm25_index.add(obs)
+                    comb_text = obs["title"] + " " + obs["narrative"]
+                    vector_index_add_guarded(obs["id"], sid, comb_text, {"kind": "observation", "logId": obs["id"]})
+                    total_indexed += 1
+    except Exception as e:
+        print(f"[rebuild_index] session-based backfill skipped: {e}")
+
+    # ---- Backfill BM25 with global memories (both schemas) ----
     memories = kv.list(KV.memories)
     for mem in memories:
         if mem.get("isLatest") is False:
@@ -1746,7 +2280,7 @@ def get_session(kv: StateKV, session_id: str) -> Optional[Dict[str, Any]]:
     return s
 
 def create_session(kv: StateKV, session: Dict[str, Any]) -> Dict[str, Any]:
-    auto_complete_old_active_sessions(kv, session["id"])
+    auto_complete_old_active_sessions(kv, session["id"], project=session.get("project"), agent_id=session.get("agentId"))
     kv.set(KV.sessions, session["id"], session)
     return session
 
@@ -1900,99 +2434,118 @@ def build_project_profile(kv: StateKV, project: str) -> Dict[str, Any]:
 def export_data(kv: StateKV, data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
     if data is None:
         data = {}
-    raw_max = data.get("maxSessions")
-    max_sessions = None
-    if raw_max is not None:
-        try:
-            max_sessions = min(max(int(raw_max), 1), 1000)
-        except Exception:
-            pass
-            
-    raw_offset = data.get("offset")
-    offset = 0
-    if raw_offset is not None:
-        try:
-            offset = max(int(raw_offset), 0)
-        except Exception:
-            pass
-            
-    all_sessions = kv.list(KV.sessions)
-    all_sessions.sort(key=lambda s: s.get("startedAt", ""), reverse=True)
-    
-    if max_sessions is not None:
-        paginated_sessions = all_sessions[offset:offset + max_sessions]
-    else:
-        paginated_sessions = all_sessions
-        
+
+    exported_at = datetime.datetime.utcnow().isoformat() + "Z"
+
+    # ---- v2 folder-based export (primary path) ----
+    folder_pairs = kv.list(KV.folders)
+    folders_export = []
+    for entry in folder_pairs:
+        fp = entry.get("folderPath")
+        aid = entry.get("agentId")
+        if not fp or not aid:
+            continue
+        meta = kv.get(KV.folder_meta(fp, aid), "meta") or {
+            "folderPath": fp,
+            "agentId": aid,
+            "lastUpdated": entry.get("lastUpdated", ""),
+            "obsCount": entry.get("obsCount", 0),
+        }
+        observations = kv.list(KV.folder_obs(fp, aid))
+        folders_export.append({
+            "folderPath": fp,
+            "agentId": aid,
+            "meta": meta,
+            "observations": observations,
+        })
+
     memories = kv.list(KV.memories)
-    summaries = kv.list(KV.summaries)
-    
-    observations = {}
-    for s in paginated_sessions:
-        sid = s.get("id")
-        if sid:
-            obs = kv.list(KV.observations(sid))
-            if obs:
-                observations[sid] = obs
-                
-    profiles = []
-    unique_projects = list(set(s.get("project") for s in paginated_sessions if s.get("project")))
-    for proj in unique_projects:
-        p = kv.get(KV.profiles, proj)
-        if p:
-            profiles.append(p)
-            
-    graph_nodes = kv.list(KV.graphNodes)
-    graph_edges = kv.list(KV.graphEdges)
-    semantic_memories = kv.list(KV.semantic)
-    procedural_memories = kv.list(KV.procedural)
-    actions = kv.list(KV.actions)
-    action_edges = kv.list(KV.actionEdges)
-    sentinels = kv.list(KV.sentinels)
-    sketches = kv.list(KV.sketches)
-    crystals = kv.list(KV.crystals)
-    facets = kv.list(KV.facets)
-    lessons = kv.list(KV.lessons)
-    insights = kv.list(KV.insights)
-    routines = kv.list(KV.routines)
-    signals = kv.list(KV.signals)
-    checkpoints = kv.list(KV.checkpoints)
-    access_logs = kv.list(KV.accessLog)
-    
-    res = {
-        "version": "0.9.21",
-        "exportedAt": datetime.datetime.utcnow().isoformat() + "Z",
-        "sessions": paginated_sessions,
-        "observations": observations,
+
+    return {
+        "folders": folders_export,
         "memories": memories,
-        "summaries": summaries
+        "exportedAt": exported_at,
+        "version": "2.0",
+    }
+
+
+def migrate_sessions_to_folders(kv: StateKV, dry_run: bool = False) -> Dict[str, Any]:
+    """Migrate legacy session-based observations to folder-based storage.
+    Non-destructive: old mem:sessions / mem:obs:* scopes are never deleted.
+    """
+    sessions = kv.list(KV.sessions)
+    migrated_sessions = 0
+    migrated_observations = 0
+    errors = []
+
+    for session in sessions:
+        session_id = session.get('id')
+        if not session_id:
+            continue
+        try:
+            fp_raw = session.get('cwd') or session.get('project') or 'unknown'
+            aid = (session.get('agentId') or 'unknown').strip()[:_MAX_PATH_LEN]
+            try:
+                fp = normalize_folder_path(fp_raw)
+            except ValueError:
+                fp = 'unknown'
+
+            obs_list = kv.list(KV.observations(session_id))
+            session_obs_count = 0
+            for obs in obs_list:
+                obs_id = obs.get('id', '')
+                if obs_id.endswith(':raw'):
+                    continue
+                folder_obs = {
+                    'id': obs_id,
+                    'folderPath': fp,
+                    'agentId': aid,
+                    'timestamp': obs.get('timestamp', ''),
+                    'text': obs.get('narrative') or obs.get('raw') or obs.get('title') or '',
+                    'type': obs.get('type', 'other'),
+                    'title': obs.get('title', ''),
+                    'concepts': obs.get('concepts') or [],
+                    'files': obs.get('files') or [],
+                    'importance': obs.get('importance', 5),
+                }
+                if isinstance(folder_obs['text'], dict):
+                    import json as _json
+                    folder_obs['text'] = _json.dumps(folder_obs['text'])[:4000]
+                folder_obs['text'] = str(folder_obs['text'])[:4000]
+
+                if not dry_run:
+                    kv.set(KV.folder_obs(fp, aid), obs_id, folder_obs)
+                session_obs_count += 1
+                migrated_observations += 1
+
+            if not dry_run and session_obs_count > 0:
+                meta_scope = KV.folder_meta(fp, aid)
+                meta = kv.get(meta_scope, 'meta') or {
+                    'folderPath': fp, 'agentId': aid, 'obsCount': 0,
+                    'lastUpdated': session.get('updatedAt', ''), 'summary': None,
+                }
+                meta['obsCount'] = meta.get('obsCount', 0) + session_obs_count
+                meta['lastUpdated'] = session.get('updatedAt', '') or meta['lastUpdated']
+                kv.set(meta_scope, 'meta', meta)
+
+                index_key = f'{fp}:{aid}'
+                kv.set(KV.folders, index_key, {
+                    'folderPath': fp,
+                    'agentId': aid,
+                    'lastUpdated': meta['lastUpdated'],
+                    'obsCount': meta['obsCount'],
+                })
+
+            migrated_sessions += 1
+        except Exception as e:
+            errors.append({'sessionId': session_id, 'error': str(e)})
+
+    return {
+        'migrated_sessions': migrated_sessions,
+        'migrated_observations': migrated_observations,
+        'errors': errors,
+        'dry_run': dry_run,
     }
-    if profiles: res["profiles"] = profiles
-    if graph_nodes: res["graphNodes"] = graph_nodes
-    if graph_edges: res["graphEdges"] = graph_edges
-    if semantic_memories: res["semanticMemories"] = semantic_memories
-    if procedural_memories: res["proceduralMemories"] = procedural_memories
-    if actions: res["actions"] = actions
-    if action_edges: res["actionEdges"] = action_edges
-    if sentinels: res["sentinels"] = sentinels
-    if sketches: res["sketches"] = sketches
-    if crystals: res["crystals"] = crystals
-    if facets: res["facets"] = facets
-    if lessons: res["lessons"] = lessons
-    if insights: res["insights"] = insights
-    if routines: res["routines"] = routines
-    if signals: res["signals"] = signals
-    if checkpoints: res["checkpoints"] = checkpoints
-    if access_logs: res["accessLogs"] = access_logs
-    
-    if max_sessions is not None:
-        res["pagination"] = {
-            "offset": offset,
-            "limit": max_sessions,
-            "total": len(all_sessions),
-            "hasMore": offset + max_sessions < len(all_sessions)
-        }
-    return res
 
 
 def set_project_profile(kv: StateKV, project: str, profile: Dict[str, Any]) -> Dict[str, Any]:
@@ -2131,17 +2684,26 @@ def auto_forget(kv: StateKV, dry_run: bool = False) -> Dict[str, Any]:
                 _vector_index.remove(mem_id)
 
         for sid, obs_id in evicted_observations:
-            obs = kv.get(KV.observations(sid), obs_id)
-            kv.delete(KV.observations(sid), obs_id)
-            if obs:
-                img = obs.get("imageData") or obs.get("imageRef")
-                if img:
-                    refs = kv.get(KV.imageRefs, img) or 0
-                    if refs > 0:
-                        kv.set(KV.imageRefs, img, refs - 1)
-            _bm25_index.remove(obs_id)
+            base_oid = obs_id.replace(":raw", "")
+            obs = kv.get(KV.observations(sid), base_oid)
+            raw_obs = kv.get(KV.observations(sid), f"{base_oid}:raw")
+            
+            kv.delete(KV.observations(sid), base_oid)
+            kv.delete(KV.observations(sid), f"{base_oid}:raw")
+            
+            for o in (obs, raw_obs):
+                if o:
+                    img = o.get("imageData") or o.get("imageRef")
+                    if img:
+                        refs = kv.get(KV.imageRefs, img) or 0
+                        if refs > 0:
+                            kv.set(KV.imageRefs, img, refs - 1)
+            
+            _bm25_index.remove(base_oid)
+            _bm25_index.remove(f"{base_oid}:raw")
             if _vector_index:
-                _vector_index.remove(obs_id)
+                _vector_index.remove(base_oid)
+                _vector_index.remove(f"{base_oid}:raw")
 
         if evicted_memories or evicted_observations:
             if _index_persistence:
@@ -2174,12 +2736,61 @@ def health_check(kv: StateKV) -> Dict[str, Any]:
         conn.close()
     except Exception:
         db_status = "disconnected"
+
+    # ---- Folder-based counts ----
+    folder_count = 0
+    agent_count = 0
+    pair_count = 0
+    observation_count = 0
+    try:
+        folder_pairs = kv.list(KV.folders)
+        pair_count = len(folder_pairs)
+        unique_folders: Set[str] = set()
+        unique_agents: Set[str] = set()
+        for entry in folder_pairs:
+            fp = entry.get("folderPath")
+            aid = entry.get("agentId")
+            if fp:
+                unique_folders.add(fp)
+            if aid:
+                unique_agents.add(aid)
+            # Use the stored obsCount in the index entry for efficiency;
+            # fall back to 0 if missing.
+            observation_count += int(entry.get("obsCount") or 0)
+        folder_count = len(unique_folders)
+        agent_count = len(unique_agents)
+    except Exception as e:
+        print(f"[health_check] folder count failed: {e}")
+
+    memory_count = 0
+    try:
+        memory_count = len(kv.list(KV.memories))
+    except Exception:
+        pass
+
+    bm25_index_size = 0
+    try:
+        bm25_index_size = _bm25_index.size
+    except Exception:
+        pass
+
+    vector_index_size = 0
+    try:
+        if _vector_index:
+            vector_index_size = _vector_index.size
+    except Exception:
+        pass
+
     return {
-        "status": "healthy" if db_status == "connected" else "degraded",
-        "service": "agentmemory",
-        "version": "0.9.8",
-        "database": "dolt",
-        "databaseStatus": db_status
+        "status": "ok" if db_status == "connected" else "degraded",
+        "folderCount": folder_count,
+        "agentCount": agent_count,
+        "pairCount": pair_count,
+        "observationCount": observation_count,
+        "memoryCount": memory_count,
+        "bm25IndexSize": bm25_index_size,
+        "vectorIndexSize": vector_index_size,
+        "dbPath": kv.db_path,
     }
 
 def strip_xml_wrappers(raw: str) -> str:
@@ -2312,10 +2923,11 @@ def summarize(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
                 "concepts": get_xml_children(cleaned, "concepts", "concept"),
             })
         except Exception as e:
+            last_error = str(e)
             print(f"[summarize] Chunk {idx+1} failed: {e}")
             
     if not partial_summaries:
-        return {"success": False, "error": "No chunks summarized successfully"}
+        return {"success": False, "error": f"No chunks summarized successfully. Last error: {last_error}"}
         
     if len(partial_summaries) == 1:
         final_summary = {
@@ -2509,6 +3121,19 @@ def consolidate(kv: StateKV, project: Optional[str] = None, min_observations: in
                 if project:
                     evolved["project"] = project
                 kv.set(KV.memories, evolved["id"], evolved)
+                try:
+                    _bm25_index.add(memory_to_observation(evolved))
+                    if existing_match:
+                        _bm25_index.remove(existing_match["id"])
+                except Exception:
+                    pass
+                comb_text = evolved["title"] + " " + evolved["content"]
+                vector_index_add_guarded(evolved["id"], "memory", comb_text, {"kind": "memory", "logId": evolved["id"]})
+                if _vector_index and existing_match:
+                    try:
+                        _vector_index.remove(existing_match["id"])
+                    except Exception:
+                        pass
                 consolidated_count += 1
             else:
                 memory = {
@@ -2529,6 +3154,12 @@ def consolidate(kv: StateKV, project: Optional[str] = None, min_observations: in
                 if project:
                     memory["project"] = project
                 kv.set(KV.memories, memory["id"], memory)
+                try:
+                    _bm25_index.add(memory_to_observation(memory))
+                except Exception:
+                    pass
+                comb_text = memory["title"] + " " + memory["content"]
+                vector_index_add_guarded(memory["id"], "memory", comb_text, {"kind": "memory", "logId": memory["id"]})
                 consolidated_count += 1
                 
         except Exception as e:
@@ -2688,10 +3319,185 @@ def consolidate(kv: StateKV, project: Optional[str] = None, min_observations: in
             "patternsAnalyzed": len(patterns)
         }
     }
+    if _index_persistence and consolidated_count > 0:
+        _index_persistence.schedule_save()
     safe_audit(kv, "consolidate", "mem::consolidate-pipeline", [], res_summary)
     commit_if_enabled(kv, f"Consolidation complete: consolidated={consolidated_count}, facts={new_facts_count}, procs={new_procs_count}", "system")
     return res_summary
 
+# =====================================================================
+# Folder Graph
+# =====================================================================
+
+def folder_color(path: str) -> str:
+    """Hash a folder path string to an HSL hex color.
+
+    Replicates the JS ``folderColor(id)`` function in src/viewer/index.html
+    exactly, using the light-mode lightness range (38 + h%14).
+
+    Algorithm (matches JS):
+        h = 0
+        for each char: h = (h * 31 + ord(char)) & 0xfffffff
+        hue = (h % 360 + 360) % 360
+        sat = 55 + (h % 25)          # percent, 55-79
+        lig = 38 + (h % 14)          # percent, 38-51 (light mode)
+        convert HSL → RGB → hex
+    """
+    h = 0
+    for ch in path:
+        h = (h * 31 + ord(ch)) & 0xFFFFFFF
+
+    hue = (h % 360 + 360) % 360
+    sat_pct = 55 + (h % 25)
+    lig_pct = 38 + (h % 14)
+
+    # HSL → RGB conversion (same formula as in JS)
+    s = sat_pct / 100.0
+    l = lig_pct / 100.0
+    a = s * min(l, 1 - l)
+
+    def f(n: int) -> str:
+        k = (n + hue / 30) % 12
+        c = l - a * max(min(k - 3, 9 - k, 1), -1)
+        return format(round(255 * c), '02x')
+
+    return '#' + f(0) + f(8) + f(4)
+
+
+def folder_graph_build(kv: StateKV) -> Dict[str, Any]:
+    """Build graph data for the viewer's Graph tab.
+
+    Reads all (folder_path, agent_id) pairs from ``KV.folders``,
+    aggregates per-folder node metadata, loads observations to collect
+    text for cross-reference edge detection, then emits three edge types:
+
+    - ``same-parent``: two folders share the same ``os.path.dirname``
+    - ``cross-ref``:   folder A's combined obs text contains folder B's path
+    - ``agent-shared``: two folders share a common agentId
+
+    Returns:
+        {"nodes": [...], "edges": [...]}
+
+    Each node::
+
+        {
+            "id": folderPath,
+            "label": basename(folderPath),
+            "folderPath": folderPath,
+            "agentIds": [...],
+            "obsCount": int,
+            "color": "#rrggbb",
+        }
+
+    Each edge::
+
+        {
+            "source": folderPath,
+            "target": folderPath,
+            "type": "same-parent" | "cross-ref" | "agent-shared",
+            # agent-shared only:
+            "agentId": str,
+        }
+
+    Edges are deduplicated on (source, target, type).
+    """
+    index_entries = kv.list(KV.folders)
+
+    # --- Build folder_map and collect obs text per (folder, agent) pair ---
+    # folder_map: folderPath -> {"folderPath", "agentIds": set, "obsCount", "color"}
+    folder_map: Dict[str, Dict[str, Any]] = {}
+    # pair_obs_texts: (folder_path, agent_id) -> combined text string
+    pair_obs_texts: Dict[Tuple[str, str], str] = {}
+
+    for entry in index_entries:
+        fp = entry.get("folderPath", "")
+        aid = entry.get("agentId", "")
+        if not fp:
+            continue
+
+        if fp not in folder_map:
+            folder_map[fp] = {
+                "folderPath": fp,
+                "agentIds": set(),
+                "obsCount": 0,
+                "color": folder_color(fp),
+            }
+
+        folder_map[fp]["agentIds"].add(aid)
+        folder_map[fp]["obsCount"] += entry.get("obsCount", 0)
+
+        # Load observations to build combined text for cross-ref detection
+        obs_scope = KV.folder_obs(fp, aid)
+        obs_list = kv.list(obs_scope)
+        combined_parts = []
+        for obs in obs_list:
+            text = obs.get("text") or ""
+            title = obs.get("title") or ""
+            combined_parts.append(f"{text} {title}")
+        pair_obs_texts[(fp, aid)] = " ".join(combined_parts)
+
+    # --- Build nodes ---
+    nodes = []
+    for fp, info in folder_map.items():
+        nodes.append({
+            "id": fp,
+            "label": os.path.basename(fp) or fp,
+            "folderPath": fp,
+            "agentIds": sorted(info["agentIds"]),
+            "obsCount": info["obsCount"],
+            "color": info["color"],
+        })
+
+    # --- Build edges ---
+    edges: List[Dict[str, Any]] = []
+    # Deduplicate on (source, target, type)
+    seen_edges: Set[Tuple[str, str, str]] = set()
+
+    def add_edge(edge: Dict[str, Any]) -> None:
+        key = (edge["source"], edge["target"], edge["type"])
+        if key not in seen_edges:
+            seen_edges.add(key)
+            edges.append(edge)
+
+    folder_paths = list(folder_map.keys())
+
+    # Edge type 1 — same-parent
+    for i in range(len(folder_paths)):
+        for j in range(i + 1, len(folder_paths)):
+            a = folder_paths[i]
+            b = folder_paths[j]
+            # Use posixpath-style dirname on forward-slash paths
+            if a.rsplit("/", 1)[0] == b.rsplit("/", 1)[0] and "/" in a and "/" in b:
+                add_edge({"source": a, "target": b, "type": "same-parent"})
+            elif os.path.dirname(a) == os.path.dirname(b) and os.path.dirname(a) != "":
+                add_edge({"source": a, "target": b, "type": "same-parent"})
+
+    # Edge type 2 — cross-reference (folder A's obs text mentions folder B's path)
+    for (fp_a, _agent_a), text_a in pair_obs_texts.items():
+        for fp_b in folder_paths:
+            if fp_b != fp_a and fp_b in text_a:
+                add_edge({"source": fp_a, "target": fp_b, "type": "cross-ref"})
+
+    # Edge type 3 — agent-shared (two folders share the same agentId)
+    # Build: agentId -> [folder_paths that have this agent]
+    agent_to_folders: Dict[str, List[str]] = {}
+    for fp, info in folder_map.items():
+        for aid in info["agentIds"]:
+            agent_to_folders.setdefault(aid, []).append(fp)
+
+    for aid, fps in agent_to_folders.items():
+        for i in range(len(fps)):
+            for j in range(i + 1, len(fps)):
+                add_edge({
+                    "source": fps[i],
+                    "target": fps[j],
+                    "type": "agent-shared",
+                    "agentId": aid,
+                })
+
+    return {"nodes": nodes, "edges": edges}
+
+
 # Setup persistence helper wire-ups
 def set_index_persistence(persistence: IndexPersistence) -> None:
     global _index_persistence

src/viewer/index.html

@@ -1119,7 +1119,7 @@
 </head>
 <body>
   <div class="app-header">
-    <a class="brand" href="#dashboard" data-tab-link="dashboard" aria-label="Open dashboard">
+    <a class="brand" href="#folders" data-tab-link="folders" aria-label="Open folders view">
       <h1>agentmemory</h1>
       <span class="version">v__AGENTMEMORY_VERSION__</span>
     </a>
@@ -1131,33 +1131,19 @@
   </div>
 
   <div class="tab-bar" id="tab-bar">
-    <button class="active" data-tab="dashboard" aria-current="page">Dashboard</button>
-    <button data-tab="graph">Graph</button>
+    <button class="active" data-tab="folders" aria-current="page">Folders</button>
     <button data-tab="memories">Memories</button>
+    <button data-tab="graph">Graph</button>
     <button data-tab="timeline">Timeline</button>
-    <button data-tab="sessions">Sessions</button>
-    <button data-tab="lessons">Lessons</button>
-    <button data-tab="actions">Actions</button>
-    <button data-tab="crystals">Crystals</button>
-    <button data-tab="audit">Audit</button>
-    <button data-tab="activity">Activity</button>
-    <button data-tab="profile">Profile</button>
-    <button data-tab="replay">Replay</button>
-    <button data-tab="personal">Personal</button>
   </div>
 
   <div id="flag-banners" class="flag-banners"></div>
   <div id="viewer-auth" class="viewer-auth"></div>
 
-  <div id="view-dashboard" class="view active"></div>
+  <div id="view-folders" class="view active"></div>
   <div id="view-graph" class="view"></div>
   <div id="view-memories" class="view"></div>
-  <div id="view-lessons" class="view"></div>
-  <div id="view-actions" class="view"></div>
-  <div id="view-crystals" class="view"></div>
   <div id="view-timeline" class="view"></div>
-  <div id="view-sessions" class="view"></div>
-  <div id="view-audit" class="view"></div>
   <div id="view-activity" class="view"></div>
   <div id="view-profile" class="view"></div>
   <div id="view-replay" class="view"></div>
@@ -1268,7 +1254,7 @@
       task: '&#9745;', other: '&#128196;'
     };
     var CB_STATE_COLORS = { closed: 'badge-green', open: 'badge-red', 'half-open': 'badge-yellow' };
-    var TAB_IDS = ['dashboard', 'graph', 'memories', 'timeline', 'sessions', 'lessons', 'actions', 'crystals', 'audit', 'activity', 'profile', 'replay', 'personal'];
+    var TAB_IDS = ['folders', 'memories', 'graph', 'timeline'];
     var VIEWER_TOKEN_STORAGE_KEY = 'agentmemory-viewer-token';
 
     var state = {
@@ -1452,14 +1438,14 @@
 
     function normalizeTab(tab) {
       var normalized = String(tab || '').replace(/^#/, '').toLowerCase();
-      return TAB_IDS.indexOf(normalized) >= 0 ? normalized : 'dashboard';
+      return TAB_IDS.indexOf(normalized) >= 0 ? normalized : 'folders';
     }
 
     function tabFromRoute() {
       try {
         return normalizeTab(decodeURIComponent(window.location.hash.slice(1)));
       } catch (_) {
-        return 'dashboard';
+        return 'folders';
       }
     }
 
@@ -1476,9 +1462,6 @@
     function switchTab(tab, opts) {
       opts = opts || {};
       tab = normalizeTab(tab);
-      if (state.activeTab === 'replay' && tab !== 'replay' && typeof stopReplayTimer === 'function') {
-        stopReplayTimer();
-      }
       if (!opts.skipRoute) {
         updateTabRoute(tab, !!opts.replaceRoute);
       }
@@ -1501,64 +1484,149 @@
 
     async function loadTab(tab) {
       switch(tab) {
-        case 'dashboard': if (!state.dashboard.loaded) await loadDashboard(); break;
-        case 'graph': if (!state.graph.loaded) await loadGraph(); break;
-        case 'memories': if (!state.memories.loaded) await loadMemories(); break;
-        case 'timeline': if (!state.timeline.loaded) await loadTimeline(); break;
-        case 'sessions': if (!state.sessions.loaded) await loadSessions(); break;
-        case 'lessons': if (!state.lessons.loaded) await loadLessons(); break;
-        case 'actions': if (!state.actions.loaded) await loadActions(); break;
-        case 'crystals': if (!state.crystals.loaded) await loadCrystals(); break;
-        case 'audit': if (!state.audit.loaded) await loadAudit(); break;
-        case 'activity': if (!state.activity.loaded) await loadActivity(); break;
-        case 'profile': if (!state.profile.loaded) await loadProfile(); break;
-        case 'replay': if (!state.replay.loaded) await loadReplay(); break;
-        case 'personal': if (!state.personal.loaded) await loadPersonal(); break;
+        case 'folders': await loadFolders(); break;
+        case 'graph': await loadGraph(); break;
+        case 'memories': await loadMemories(); break;
+        case 'timeline': await loadTimeline(); break;
       }
     }
 
     async function loadDashboard() {
-      var el = document.getElementById('view-dashboard');
-      el.innerHTML = '<div class="loading">Loading dashboard...</div>';
+      // Dashboard removed — redirect to folders
+      switchTab('folders');
+    }
+
+    // =====================================================================
+    // Folders Tab
+    // =====================================================================
+    async function loadFolders() {
+      var el = document.getElementById('view-folders');
+      if (!el) return;
+      el.innerHTML = '<div class="loading">Loading folders...</div>';
       try {
-        var results = await Promise.all([
-          apiGet('health'),
-          apiGet('sessions'),
-          apiGet('memories?latest=true&limit=500'),
-          apiGet('graph/stats'),
-          apiGet('audit?limit=5'),
-          apiGet('semantic'),
-          apiGet('procedural'),
-          apiGet('relations'),
-          apiGet('lessons'),
-          apiGet('crystals')
-        ]);
-        state.dashboard.health = results[0];
-        state.dashboard.sessions = (results[1] && results[1].sessions) || [];
-        state.dashboard.memories = (results[2] && results[2].memories) || [];
-        state.dashboard.graphStats = results[3];
-        state.dashboard.recentAudit = (results[4] && results[4].entries) || [];
-        state.dashboard.semantic = (results[5] && results[5].items) || (results[5] && results[5].facts) || (results[5] && results[5].semantic) || [];
-        state.dashboard.procedural = (results[6] && results[6].items) || (results[6] && results[6].procedures) || (results[6] && results[6].procedural) || [];
-        state.dashboard.lessons = (results[8] && results[8].lessons) || [];
-        state.dashboard.crystals = (results[9] && results[9].crystals) || [];
-        state.dashboard.relations = (results[7] && results[7].relations) || [];
-        state.dashboard.loaded = true;
-        renderDashboard();
-      } catch (err) {
-        var msg = (err && err.message) ? err.message : String(err);
-        console.error('[viewer] loadDashboard failed:', err);
-        el.innerHTML =
-          '<div class="loading" style="color:var(--accent);">' +
-          'Dashboard failed to load: ' + msg +
-          '<br><br><span style="font-size:12px;color:var(--ink-muted);">' +
-          'Check the browser console for the full error. If you see CSP ' +
-          'violations, please open an issue with the agentmemory version ' +
-          '(top-right of the viewer) and the violation text.' +
-          '</span></div>';
+        var result = await apiPost('folders-list', null, 'GET');
+        var folders = (result && result.folders) || [];
+        renderFolderList(folders);
+      } catch(err) {
+        el.innerHTML = '<div class="loading" style="color:var(--accent);">Failed to load folders: ' + esc(String(err)) + '</div>';
+      }
+    }
+
+    function renderFolderList(folders) {
+      var el = document.getElementById('view-folders');
+      if (!el) return;
+      if (folders.length === 0) {
+        el.innerHTML = '<div class="empty-state"><div class="empty-icon">&#128193;</div><p>No folder memories yet.</p><p style="font-size:13px;color:var(--ink-muted);margin-top:8px;">Use <code>agent_observe</code> with a <code>folderPath</code> to start recording.</p></div>';
+        return;
       }
+      var html = '<div style="padding:20px 24px;">';
+      html += '<h2 style="font-family:var(--font-display);font-size:18px;font-weight:700;color:var(--ink);margin-bottom:16px;">Folder Memories</h2>';
+      html += '<table style="width:100%;border-collapse:collapse;font-family:var(--font-ui);font-size:13px;">';
+      html += '<thead><tr style="border-bottom:2px solid var(--border);">';
+      html += '<th style="text-align:left;padding:8px 12px;color:var(--ink-muted);font-weight:600;">Folder</th>';
+      html += '<th style="text-align:left;padding:8px 12px;color:var(--ink-muted);font-weight:600;">Agent</th>';
+      html += '<th style="text-align:right;padding:8px 12px;color:var(--ink-muted);font-weight:600;">Observations</th>';
+      html += '<th style="text-align:left;padding:8px 12px;color:var(--ink-muted);font-weight:600;">Last Updated</th>';
+      html += '</tr></thead><tbody>';
+      folders.forEach(function(f) {
+        var fp = f.folderPath || '';
+        var aid = f.agentId || '';
+        var obs = f.obsCount || 0;
+        var updated = f.lastUpdated ? new Date(f.lastUpdated).toLocaleString() : '—';
+        html += '<tr class="folder-row" data-folder="' + esc(fp) + '" data-agent="' + esc(aid) + '" style="border-bottom:1px solid var(--border-light);cursor:pointer;" onmouseover="this.style.background=\'var(--bg-subtle)\'" onmouseout="this.style.background=\'\'">';
+        html += '<td style="padding:10px 12px;max-width:320px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;" title="' + esc(fp) + '"><span style="font-family:var(--font-mono);font-size:12px;">' + esc(fp) + '</span></td>';
+        html += '<td style="padding:10px 12px;"><span style="background:var(--bg-inset);padding:2px 8px;border-radius:3px;font-size:11px;font-weight:600;">' + esc(aid) + '</span></td>';
+        html += '<td style="padding:10px 12px;text-align:right;font-weight:600;color:var(--accent);">' + obs + '</td>';
+        html += '<td style="padding:10px 12px;color:var(--ink-muted);font-size:12px;">' + esc(updated) + '</td>';
+        html += '</tr>';
+      });
+      html += '</tbody></table></div>';
+      el.innerHTML = html;
+
+      el.querySelectorAll('.folder-row').forEach(function(row) {
+        row.addEventListener('click', function() {
+          loadFolderDetail(row.dataset.folder, row.dataset.agent);
+        });
+      });
     }
 
+    async function loadFolderDetail(folderPath, agentId) {
+      var el = document.getElementById('view-folders');
+      if (!el) return;
+      el.innerHTML = '<div class="loading">Loading observations...</div>';
+      try {
+        var params = 'folderPath=' + encodeURIComponent(folderPath) + '&agentId=' + encodeURIComponent(agentId);
+        var result = await apiFetchRaw('/agentmemory/folder/observations?' + params);
+        var obs = (result && result.observations) || [];
+
+        var html = '<div style="padding:20px 24px;">';
+        html += '<div style="display:flex;align-items:center;gap:12px;margin-bottom:20px;">';
+        html += '<button onclick="loadFolders()" style="background:none;border:1px solid var(--border-light);padding:6px 14px;cursor:pointer;font-family:var(--font-ui);font-size:12px;border-radius:3px;">&larr; Back</button>';
+        html += '<span style="font-family:var(--font-mono);font-size:13px;color:var(--ink);">' + esc(folderPath) + '</span>';
+        html += '<span style="background:var(--bg-inset);padding:2px 8px;border-radius:3px;font-size:11px;font-weight:600;">' + esc(agentId) + '</span>';
+        html += '<span style="margin-left:auto;font-size:12px;color:var(--ink-muted);">' + obs.length + ' observations</span>';
+        html += '</div>';
+
+        if (obs.length === 0) {
+          html += '<div class="empty-state"><p>No observations found.</p></div>';
+        } else {
+          obs.forEach(function(o) {
+            var ts = o.timestamp ? new Date(o.timestamp).toLocaleString() : '';
+            var typeColor = {'file_edit':'var(--blue)','command_run':'var(--orange)','search':'var(--green)','error':'var(--red)','conversation':'var(--purple)'}[o.type] || 'var(--ink-muted)';
+            html += '<div style="border:1px solid var(--border-light);border-radius:4px;padding:14px 16px;margin-bottom:10px;background:var(--bg);">';
+            html += '<div style="display:flex;align-items:center;gap:8px;margin-bottom:6px;">';
+            html += '<span style="font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:0.08em;color:' + typeColor + ';background:var(--bg-subtle);padding:2px 7px;border-radius:3px;">' + esc(o.type || 'other') + '</span>';
+            html += '<span style="font-size:11px;color:var(--ink-muted);font-family:var(--font-mono);">' + esc(ts) + '</span>';
+            html += '</div>';
+            if (o.title) html += '<div style="font-weight:600;font-size:14px;color:var(--ink);margin-bottom:4px;">' + esc(o.title) + '</div>';
+            if (o.text) html += '<div style="font-size:13px;color:var(--ink-secondary);line-height:1.5;white-space:pre-wrap;">' + esc(o.text.length > 300 ? o.text.slice(0,300)+'…' : o.text) + '</div>';
+            html += '</div>';
+          });
+        }
+
+        html += '<div style="margin-top:20px;padding-top:16px;border-top:1px solid var(--border-light);">';
+        html += '<button onclick="deleteFolderMemory(\'' + esc(folderPath).replace(/'/g,"\\'") + '\',\'' + esc(agentId).replace(/'/g,"\\'") + '\')" style="background:var(--accent);color:white;border:none;padding:8px 18px;cursor:pointer;font-family:var(--font-ui);font-size:13px;border-radius:3px;">Delete folder memory</button>';
+        html += '</div></div>';
+        el.innerHTML = html;
+      } catch(err) {
+        el.innerHTML = '<div style="padding:20px;"><button onclick="loadFolders()" style="background:none;border:1px solid var(--border-light);padding:6px 14px;cursor:pointer;">&larr; Back</button><div style="margin-top:16px;color:var(--accent);">Error: ' + esc(String(err)) + '</div></div>';
+      }
+    }
+
+    async function deleteFolderMemory(folderPath, agentId) {
+      if (!confirm('Delete all observations for ' + folderPath + ' / ' + agentId + '?')) return;
+      try {
+        await apiFetchRaw('/agentmemory/forget', { method: 'POST', body: JSON.stringify({ folderPath: folderPath, agentId: agentId }) });
+        loadFolders();
+      } catch(err) {
+        alert('Delete failed: ' + String(err));
+      }
+    }
+
+    async function apiFetchRaw(path, opts) {
+      opts = opts || {};
+      var headers = Object.assign({ 'Content-Type': 'application/json' }, opts.headers || {});
+      if (state.token) headers['Authorization'] = 'Bearer ' + state.token;
+      var url = (path.startsWith('/') ? '' : '/agentmemory/') + path;
+      var res = await fetch(url, Object.assign({}, opts, { headers: headers }));
+      if (!res.ok) throw new Error(res.status + ' ' + res.statusText);
+      return res.json();
+    }
+
+    async function apiPost(endpoint, body, method) {
+      method = method || 'POST';
+      var headers = { 'Content-Type': 'application/json' };
+      if (state.token) headers['Authorization'] = 'Bearer ' + state.token;
+      var url = '/agentmemory/' + endpoint;
+      var opts = { method: method, headers: headers };
+      if (body !== null && body !== undefined) opts.body = JSON.stringify(body);
+      var res = await fetch(url, opts);
+      if (!res.ok) throw new Error(res.status + ' ' + res.statusText);
+      return res.json();
+    }
+
+
+
     function renderDashboard() {
       var el = document.getElementById('view-dashboard');
       var d = state.dashboard;
@@ -1851,146 +1919,45 @@
       var el = document.getElementById('view-graph');
       el.innerHTML = '<div class="graph-container"><div class="graph-canvas-wrap"><canvas id="graph-canvas"></canvas><div class="graph-controls"><button title="Zoom In" data-action="zoom-graph" data-dir="1">+</button><button title="Zoom Out" data-action="zoom-graph" data-dir="-1">&minus;</button><div class="ctrl-divider"></div><button title="Recenter" data-action="recenter-graph">⌖</button></div><div class="graph-tooltip" id="graph-tooltip"></div></div><div class="graph-sidebar" id="graph-sidebar"></div></div>';
 
-      var results = await Promise.all([
-        apiGet('sessions'),
-        apiGet('memories?latest=true&limit=2000'),
-        apiGet('graph/stats')
-      ]);
-
-      var sessions = (results[0] && results[0].sessions) || [];
-      var memories = (results[1] && results[1].memories) || [];
-      var stats = results[2] || {};
-
       state.graph.queryError = null;
+      var graphData;
+      try {
+        graphData = await apiFetchRaw('/agentmemory/graph');
+      } catch(err) {
+        state.graph.queryError = String(err);
+        graphData = { nodes: [], edges: [] };
+      }
 
-      // Extract unique folders (projects)
-      var folderMap = {};
-      sessions.forEach(function(s) {
-        var path = s.project ? String(s.project).trim() : '';
-        if (!path) return;
-        if (!path.includes('/') && !path.includes('\\')) return;
-        if (!folderMap[path]) {
-          folderMap[path] = {
-            id: path,
-            name: path.split(/[\\/]/).pop() || path,
-            fullPath: path,
-            type: 'folder',
-            sessions: [],
-            memories: [],
-            concepts: new Set(),
-            firstPrompts: [],
-            summaries: []
-          };
-        }
-        folderMap[path].sessions.push(s);
-        if (s.firstPrompt) folderMap[path].firstPrompts.push(s.firstPrompt);
-        if (s.summary) folderMap[path].summaries.push(s.summary);
-      });
-
-      memories.forEach(function(m) {
-        var path = m.project ? String(m.project).trim() : '';
-        if (!path) return;
-        if (!path.includes('/') && !path.includes('\\')) return;
-        if (!folderMap[path]) {
-          // If the folder is not in sessions, create it
-          folderMap[path] = {
-            id: path,
-            name: path.split(/[\\/]/).pop() || path,
-            fullPath: path,
-            type: 'folder',
-            sessions: [],
-            memories: [],
-            concepts: new Set(),
-            firstPrompts: [],
-            summaries: []
-          };
-        }
-        folderMap[path].memories.push(m);
-        if (m.concepts && Array.isArray(m.concepts)) {
-          m.concepts.forEach(function(c) {
-            folderMap[path].concepts.add(c.toLowerCase());
-          });
-        }
+      // Map server nodes to viewer format
+      var folders = (graphData.nodes || []).map(function(n) {
+        return {
+          id: n.folderPath || n.id,
+          name: n.label || (n.folderPath || n.id).split(/[\\/]/).pop() || n.id,
+          fullPath: n.folderPath || n.id,
+          type: 'folder',
+          agentIds: n.agentIds || [],
+          obsCount: n.obsCount || 0,
+          color: n.color || folderColor(n.folderPath || n.id),
+          properties: {
+            description: 'Agents: ' + (n.agentIds || []).join(', ') + '<br>Observations: ' + (n.obsCount || 0),
+            fullPath: n.folderPath || n.id,
+            obsCount: n.obsCount || 0
+          }
+        };
       });
 
-      var folders = Object.values(folderMap);
-      
-      // Compute detailed properties/descriptions
-      folders.forEach(function(f) {
-        var desc = '';
-        if (f.summaries.length > 0) {
-          desc += '<strong>Summaries:</strong><br>' + f.summaries.slice(0, 3).map(function(s) { return '&bull; ' + esc(s); }).join('<br>') + '<br><br>';
-        } else if (f.firstPrompts.length > 0) {
-          desc += '<strong>Prompts:</strong><br>' + f.firstPrompts.slice(0, 3).map(function(p) { return '&bull; ' + esc(p); }).join('<br>') + '<br><br>';
-        }
-        
-        var conceptsArr = Array.from(f.concepts);
-        if (conceptsArr.length > 0) {
-          desc += '<strong>Concepts:</strong><br>' + conceptsArr.slice(0, 10).map(function(c) { return '<span class="tag">' + esc(c) + '</span>'; }).join(' ') + '<br><br>';
-        }
-        
-        if (f.memories.length > 0) {
-          desc += '<strong>Memories:</strong><br>' + f.memories.slice(0, 5).map(function(m) { return '&bull; ' + esc(m.title); }).join('<br>');
-        }
-        
-        f.properties = {
-          description: desc || 'No description available for this folder.',
-          fullPath: f.fullPath,
-          sessionCount: f.sessions.length,
-          memoryCount: f.memories.length
+      // Map server edges to viewer format
+      var edges = (graphData.edges || []).map(function(e) {
+        return {
+          id: e.source + '->' + e.target + ':' + e.type,
+          sourceNodeId: e.source,
+          targetNodeId: e.target,
+          type: e.type || 'connection',
+          agentId: e.agentId,
+          weight: e.type === 'cross-ref' ? 2 : 1
         };
       });
 
-      // Compute edges (connections between folders)
-      var edges = [];
-      for (var i = 0; i < folders.length; i++) {
-        for (var j = i + 1; j < folders.length; j++) {
-          var f1 = folders[i];
-          var f2 = folders[j];
-          
-          var sharedConcepts = [];
-          f1.concepts.forEach(function(c) {
-            if (f2.concepts.has(c)) {
-              sharedConcepts.push(c);
-            }
-          });
-          
-          var path1 = f1.fullPath.split(/[\\/]/).filter(Boolean);
-          var path2 = f2.fullPath.split(/[\\/]/).filter(Boolean);
-          var commonSubdirs = 0;
-          for (var k = 0; k < Math.min(path1.length, path2.length); k++) {
-            if (path1[k].toLowerCase() === path2[k].toLowerCase()) {
-              var p = path1[k].toLowerCase();
-              if (p !== 'c:' && p !== 'd:' && p !== 'downloads' && p !== 'projects' && p !== 'other projects') {
-                commonSubdirs++;
-              }
-            } else {
-              break;
-            }
-          }
-          
-          var connectionType = [];
-          var weight = 0;
-          if (sharedConcepts.length > 0) {
-            connectionType.push('Shared concepts: ' + sharedConcepts.slice(0, 2).join(', '));
-            weight += sharedConcepts.length * 0.8;
-          }
-          if (commonSubdirs > 0) {
-            connectionType.push('Common parent path');
-            weight += commonSubdirs * 1.5;
-          }
-          
-          if (weight > 0) {
-            edges.push({
-              id: f1.fullPath + '->' + f2.fullPath,
-              sourceNodeId: f1.fullPath,
-              targetNodeId: f2.fullPath,
-              type: connectionType.join(' & '),
-              weight: Math.min(5, weight)
-            });
-          }
-        }
-      }
 
       state.graph.nodes = folders;
       state.graph.edges = edges;
@@ -2810,7 +2777,7 @@
 
     async function confirmDeleteMemory(id) {
       closeModal();
-      await apiDelete('governance/memories', { memoryIds: [id], reason: 'Deleted via viewer' });
+      await apiPost('forget', { memoryId: id });
       state.memories.loaded = false;
       loadMemories();
     }
@@ -2819,63 +2786,132 @@
       document.getElementById('modal-overlay').classList.remove('open');
     }
 
-    async function loadTimeline() {
+    // =====================================================================
+    // Timeline Tab — folder activity feed
+    // =====================================================================
+    var tlFolderFilter = '';
+    var tlAgentFilter = '';
+
+    async function loadTimeline(folderPath, agentId) {
       var el = document.getElementById('view-timeline');
+      if (!el) return;
       el.innerHTML = '<div class="loading">Loading timeline...</div>';
-      var sessResult = await apiGet('sessions');
-      var sessions = (sessResult && sessResult.sessions) || [];
-      state.timeline.loaded = true;
-
-      if (sessions.length > 0 && !state.timeline.sessionId) {
-        var sorted = sessions.slice().sort(function(a, b) { return (b.startedAt || '').localeCompare(a.startedAt || ''); });
-        var firstSelectable = sorted.find(function(s) { return sessionId(s); });
-        state.timeline.sessionId = firstSelectable ? sessionId(firstSelectable) : '';
+      try {
+        var body = { limit: 100 };
+        if (folderPath) body.folderPath = folderPath;
+        if (agentId) body.agentId = agentId;
+        var result = await apiFetchRaw('/agentmemory/timeline', {
+          method: 'POST',
+          body: JSON.stringify(body)
+        });
+        var obs = (result && result.observations) || [];
+        renderTimeline(obs);
+      } catch(err) {
+        el.innerHTML = '<div class="loading" style="color:var(--accent);">Failed to load timeline: ' + esc(String(err)) + '</div>';
       }
-
-      renderTimelineToolbar(sessions);
-      if (state.timeline.sessionId) await loadObservations();
     }
 
-    function renderTimelineToolbar(sessions) {
+    function renderTimeline(obs) {
       var el = document.getElementById('view-timeline');
-      var html = '<div class="toolbar">';
-      html += '<select id="tl-session"><option value="">Select session</option>';
-      sessions.sort(function(a, b) { return (b.startedAt || '').localeCompare(a.startedAt || ''); }).forEach(function(s) {
-        var id = sessionId(s);
-        var disabled = id ? '' : ' disabled';
-        html += '<option value="' + esc(id) + '"' + (id && state.timeline.sessionId === id ? ' selected' : '') + disabled + '>' + esc(sessionLabel(s)) + '</option>';
+      if (!el) return;
+
+      // Collect unique agents for dropdown
+      var agents = [];
+      var agentSeen = {};
+      obs.forEach(function(o) {
+        if (o.agentId && !agentSeen[o.agentId]) {
+          agentSeen[o.agentId] = true;
+          agents.push(o.agentId);
+        }
+      });
+
+      var html = '<div style="padding:16px 24px;">';
+      // Filter bar
+      html += '<div style="display:flex;gap:12px;align-items:center;margin-bottom:16px;flex-wrap:wrap;">';
+      html += '<input id="tl-folder-filter" type="text" placeholder="Filter by folder path..." value="' + esc(tlFolderFilter) + '" style="flex:1;min-width:200px;padding:7px 12px;border:1px solid var(--border-light);background:var(--bg);color:var(--ink);font-family:var(--font-mono);font-size:12px;">';
+      html += '<select id="tl-agent-filter" style="padding:7px 12px;border:1px solid var(--border-light);background:var(--bg);color:var(--ink);font-family:var(--font-ui);font-size:12px;">';
+      html += '<option value="">All agents</option>';
+      agents.forEach(function(a) {
+        html += '<option value="' + esc(a) + '"' + (tlAgentFilter === a ? ' selected' : '') + '>' + esc(a) + '</option>';
       });
       html += '</select>';
-      html += '<select id="tl-importance"><option value="0">All importance</option>';
-      for (var i = 1; i <= 9; i++) {
-        html += '<option value="' + i + '"' + (state.timeline.minImportance === i ? ' selected' : '') + '>&ge; ' + i + '</option>';
+      html += '<span style="font-size:12px;color:var(--ink-muted);">' + obs.length + ' observations</span>';
+      html += '</div>';
+
+      // Cards
+      html += '<div id="tl-cards">';
+      if (obs.length === 0) {
+        html += '<div class="empty-state"><div class="empty-icon">&#128337;</div><p>No observations found.</p></div>';
+      } else {
+        obs.forEach(function(o) {
+          html += renderTimelineCard(o);
+        });
       }
-      html += '</select></div>';
-      html += '<div id="tl-content"></div>';
+      html += '</div></div>';
       el.innerHTML = html;
 
-      document.getElementById('tl-session').addEventListener('change', function() {
-        state.timeline.sessionId = this.value;
-        state.timeline.page = 0;
-        loadObservations();
-      });
-      document.getElementById('tl-importance').addEventListener('change', function() {
-        state.timeline.minImportance = parseInt(this.value);
-        renderObservations();
-      });
+      // Wire up filters
+      var folderInput = document.getElementById('tl-folder-filter');
+      var agentSelect = document.getElementById('tl-agent-filter');
+      if (folderInput) {
+        folderInput.addEventListener('input', function() {
+          tlFolderFilter = this.value;
+          loadTimeline(tlFolderFilter || undefined, tlAgentFilter || undefined);
+        });
+      }
+      if (agentSelect) {
+        agentSelect.addEventListener('change', function() {
+          tlAgentFilter = this.value;
+          loadTimeline(tlFolderFilter || undefined, tlAgentFilter || undefined);
+        });
+      }
     }
 
-    async function loadObservations() {
-      var content = document.getElementById('tl-content');
-      if (!content) return;
-      if (!state.timeline.sessionId) {
-        content.innerHTML = '<div class="empty-state"><div class="empty-icon">&#128337;</div><p>Select a session to view observations</p></div>';
-        return;
+    function renderTimelineCard(o) {
+      var ts = o.timestamp ? new Date(o.timestamp).toLocaleString() : '';
+      var typeColors = {
+        'file_edit': 'var(--blue)', 'file_write': 'var(--blue)', 'file_read': 'var(--cyan)',
+        'command_run': 'var(--orange)', 'search': 'var(--green)',
+        'error': 'var(--red)', 'conversation': 'var(--purple)', 'subagent': 'var(--yellow)'
+      };
+      var typeColor = typeColors[o.type] || 'var(--ink-muted)';
+      var fp = o.folderPath || '';
+      var fpShort = fp.split(/[\\/]/).slice(-2).join('/');
+      var html = '<div style="border:1px solid var(--border-light);border-radius:4px;padding:12px 16px;margin-bottom:8px;background:var(--bg);">';
+      html += '<div style="display:flex;align-items:center;gap:8px;margin-bottom:6px;flex-wrap:wrap;">';
+      html += '<span style="font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:0.08em;color:' + typeColor + ';background:var(--bg-subtle);padding:2px 7px;border-radius:3px;">' + esc(o.type || 'other') + '</span>';
+      html += '<span style="font-size:10px;font-weight:600;background:var(--bg-inset);padding:2px 7px;border-radius:3px;">' + esc(o.agentId || '') + '</span>';
+      html += '<span style="font-size:11px;color:var(--ink-muted);font-family:var(--font-mono);" title="' + esc(fp) + '">' + esc(fpShort) + '</span>';
+      html += '<span style="margin-left:auto;font-size:11px;color:var(--ink-faint);font-family:var(--font-mono);">' + esc(ts) + '</span>';
+      html += '</div>';
+      if (o.title) html += '<div style="font-weight:600;font-size:13px;color:var(--ink);margin-bottom:3px;">' + esc(o.title) + '</div>';
+      if (o.text) {
+        var excerpt = o.text.length > 200 ? o.text.slice(0, 200) + '…' : o.text;
+        html += '<div style="font-size:12px;color:var(--ink-secondary);line-height:1.5;">' + esc(excerpt) + '</div>';
       }
-      content.innerHTML = '<div class="loading">Loading observations...</div>';
-      var result = await apiGet('observations?sessionId=' + encodeURIComponent(state.timeline.sessionId));
-      state.timeline.observations = (result && result.observations) || [];
-      renderObservations();
+      html += '</div>';
+      return html;
+    }
+
+    function prependTimelineCard(obs) {
+      var cards = document.getElementById('tl-cards');
+      if (!cards) return;
+      var div = document.createElement('div');
+      div.innerHTML = renderTimelineCard(obs);
+      cards.insertBefore(div.firstChild, cards.firstChild);
+    }
+
+    function updateFolderBadge(folderPath, agentId) {
+      var rows = document.querySelectorAll('.folder-row');
+      rows.forEach(function(row) {
+        if (row.dataset.folder === folderPath && row.dataset.agent === agentId) {
+          var countCell = row.querySelector('td:nth-child(3)');
+          if (countCell) {
+            var cur = parseInt(countCell.textContent) || 0;
+            countCell.textContent = cur + 1;
+          }
+        }
+      });
     }
 
     var tlTypeFilter = '';
@@ -4128,7 +4164,19 @@
           if (state.ws !== ws) return;
           try {
             var msg = JSON.parse(e.data);
-            if (msg.type === 'stream' && msg.event) {
+            if (msg.type === 'folder_observation') {
+              // New folder-based broadcast
+              if (state.activeTab === 'timeline') {
+                prependTimelineCard(msg.data || {});
+              }
+              if (state.activeTab === 'folders') {
+                updateFolderBadge(msg.folderPath, msg.agentId);
+              }
+            } else if (msg.type === 'raw_observation' || msg.type === 'compressed_observation') {
+              if (msg.data && msg.data.observation) {
+                routeWsMessage({ observation: msg.data.observation });
+              }
+            } else if (msg.type === 'stream' && msg.event) {
               handleStreamEvent(msg);
             } else if (msg.event_type && msg.data) {
               handleStreamEvent({ event: { type: 'create', data: msg.data, event_type: msg.event_type } });

tests/__init__.py

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

tests/test_folder_graph_build.py

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

tests/test_folder_observe.py

@@ -0,0 +1,119 @@
+"""Unit tests for folder_observe (REQ-008, REQ-010, REQ-011, REQ-015)."""
+import sys
+import os
+import pytest
+import tempfile
+import datetime
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from db import StateKV
+import functions
+from functions import folder_observe, KV
+
+
+def make_kv(tmp_path):
+    db_path = os.path.join(str(tmp_path), 'test.db')
+    return StateKV(db_path=db_path)
+
+
+def base_payload(**overrides):
+    payload = {
+        'folderPath': '/home/user/projects/myapp',
+        'agentId': 'kiro',
+        'text': 'Edited src/app.py to add a new route',
+        'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+    }
+    payload.update(overrides)
+    return payload
+
+
+class TestFolderObserveMissingFields:
+    def test_missing_folder_path(self, tmp_path):
+        kv = make_kv(tmp_path)
+        with pytest.raises(ValueError, match='folderPath'):
+            folder_observe(kv, base_payload(folderPath=''))
+
+    def test_missing_agent_id(self, tmp_path):
+        kv = make_kv(tmp_path)
+        with pytest.raises(ValueError, match='agentId'):
+            folder_observe(kv, base_payload(agentId=''))
+
+    def test_missing_text(self, tmp_path):
+        kv = make_kv(tmp_path)
+        with pytest.raises(ValueError, match='text'):
+            folder_observe(kv, base_payload(text=''))
+
+    def test_missing_timestamp_defaults(self, tmp_path):
+        kv = make_kv(tmp_path)
+        payload = base_payload()
+        del payload['timestamp']
+        # timestamp is required — should raise
+        with pytest.raises(ValueError, match='timestamp'):
+            folder_observe(kv, payload)
+
+
+class TestFolderObserveSuccess:
+    def test_returns_observation_id(self, tmp_path):
+        kv = make_kv(tmp_path)
+        result = folder_observe(kv, base_payload())
+        assert 'observationId' in result
+        assert result['observationId'].startswith('fobs_')
+
+    def test_obs_stored_in_kv(self, tmp_path):
+        kv = make_kv(tmp_path)
+        result = folder_observe(kv, base_payload())
+        obs_id = result['observationId']
+        fp = 'home/user/projects/myapp'  # normalized
+        stored = kv.get(KV.folder_obs(fp, 'kiro'), obs_id)
+        assert stored is not None
+        assert stored['id'] == obs_id
+
+    def test_obs_count_incremented(self, tmp_path):
+        kv = make_kv(tmp_path)
+        folder_observe(kv, base_payload())
+        folder_observe(kv, base_payload())
+        fp = 'home/user/projects/myapp'
+        meta = kv.get(KV.folder_meta(fp, 'kiro'), 'meta')
+        assert meta is not None
+        assert meta['obsCount'] == 2
+
+    def test_folders_index_upserted(self, tmp_path):
+        kv = make_kv(tmp_path)
+        folder_observe(kv, base_payload())
+        fp = 'home/user/projects/myapp'
+        entry = kv.get(KV.folders, f'{fp}:kiro')
+        assert entry is not None
+        assert entry['folderPath'] == fp
+        assert entry['agentId'] == 'kiro'
+
+    def test_text_capped_at_4000(self, tmp_path):
+        kv = make_kv(tmp_path)
+        long_text = 'x' * 5000
+        result = folder_observe(kv, base_payload(text=long_text))
+        fp = 'home/user/projects/myapp'
+        stored = kv.get(KV.folder_obs(fp, 'kiro'), result['observationId'])
+        assert len(stored['text']) <= 4000
+
+
+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())
+        with pytest.raises(ValueError, match='limit'):
+            folder_observe(kv, base_payload())
+
+
+class TestFolderObservePairIsolation:
+    def test_different_pairs_isolated(self, tmp_path):
+        kv = make_kv(tmp_path)
+        folder_observe(kv, base_payload(folderPath='/home/user/proj-a', agentId='kiro'))
+        folder_observe(kv, base_payload(folderPath='/home/user/proj-b', agentId='claude'))
+        fp_a = 'home/user/proj-a'
+        fp_b = 'home/user/proj-b'
+        obs_a = kv.list(KV.folder_obs(fp_a, 'kiro'))
+        obs_b = kv.list(KV.folder_obs(fp_b, 'claude'))
+        ids_a = {o['id'] for o in obs_a}
+        ids_b = {o['id'] for o in obs_b}
+        assert ids_a.isdisjoint(ids_b)

tests/test_forget.py

@@ -0,0 +1,102 @@
+"""Unit tests for forget() folder-based deletion (REQ-029–REQ-033)."""
+import sys
+import os
+import pytest
+import datetime
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from db import StateKV
+from functions import folder_observe, forget, KV
+
+
+def make_kv(tmp_path):
+    db_path = os.path.join(str(tmp_path), 'test.db')
+    return StateKV(db_path=db_path)
+
+
+def add_obs(kv, folder='/home/user/proj', agent='kiro', n=1):
+    ids = []
+    for i in range(n):
+        result = folder_observe(kv, {
+            'folderPath': folder,
+            'agentId': agent,
+            'text': f'observation {i}',
+            'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+        })
+        ids.append(result['observationId'])
+    return ids
+
+
+class TestForgetFullPair:
+    def test_full_deletion_clears_obs(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, n=3)
+        fp = 'home/user/proj'
+        result = forget(kv, {'folderPath': '/home/user/proj', 'agentId': 'kiro'})
+        assert result['deleted'] >= 3
+        obs = kv.list(KV.folder_obs(fp, 'kiro'))
+        assert len(obs) == 0
+
+    def test_full_deletion_removes_index_entry(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv)
+        fp = 'home/user/proj'
+        forget(kv, {'folderPath': '/home/user/proj', 'agentId': 'kiro'})
+        entry = kv.get(KV.folders, f'{fp}:kiro')
+        assert entry is None
+
+    def test_full_deletion_removes_meta(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv)
+        fp = 'home/user/proj'
+        forget(kv, {'folderPath': '/home/user/proj', 'agentId': 'kiro'})
+        meta = kv.get(KV.folder_meta(fp, 'kiro'), 'meta')
+        assert meta is None
+
+    def test_deleted_count_matches(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, n=5)
+        result = forget(kv, {'folderPath': '/home/user/proj', 'agentId': 'kiro'})
+        assert result['deleted'] == 5
+
+
+class TestForgetPartial:
+    def test_partial_deletion(self, tmp_path):
+        kv = make_kv(tmp_path)
+        ids = add_obs(kv, n=4)
+        fp = 'home/user/proj'
+        to_delete = ids[:2]
+        result = forget(kv, {
+            'folderPath': '/home/user/proj',
+            'agentId': 'kiro',
+            'observationIds': to_delete,
+        })
+        assert result['deleted'] == 2
+        remaining = kv.list(KV.folder_obs(fp, 'kiro'))
+        remaining_ids = {o['id'] for o in remaining}
+        for oid in to_delete:
+            assert oid not in remaining_ids
+
+    def test_partial_decrements_obs_count(self, tmp_path):
+        kv = make_kv(tmp_path)
+        ids = add_obs(kv, n=4)
+        fp = 'home/user/proj'
+        forget(kv, {
+            'folderPath': '/home/user/proj',
+            'agentId': 'kiro',
+            'observationIds': ids[:2],
+        })
+        meta = kv.get(KV.folder_meta(fp, 'kiro'), 'meta')
+        assert meta['obsCount'] == 2
+
+
+class TestForgetMemory:
+    def test_delete_global_memory(self, tmp_path):
+        kv = make_kv(tmp_path)
+        from functions import remember
+        result = remember(kv, {'content': 'Important insight', 'type': 'fact'})
+        mem_id = result['memory']['id']
+        forget_result = forget(kv, {'memoryId': mem_id})
+        assert forget_result['deleted'] >= 1
+        stored = kv.get(KV.memories, mem_id)
+        assert stored is None

tests/test_graph.py

@@ -0,0 +1,99 @@
+"""Unit tests for folder_graph_build (REQ-023–REQ-028)."""
+import sys
+import os
+import pytest
+import datetime
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from db import StateKV
+from functions import folder_observe, folder_graph_build
+
+
+def make_kv(tmp_path):
+    db_path = os.path.join(str(tmp_path), 'test.db')
+    return StateKV(db_path=db_path)
+
+
+def add_obs(kv, folder, agent='kiro', text='obs'):
+    folder_observe(kv, {
+        'folderPath': folder,
+        'agentId': agent,
+        'text': text,
+        'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+    })
+
+
+class TestGraphEmpty:
+    def test_empty_kv_returns_empty(self, tmp_path):
+        kv = make_kv(tmp_path)
+        result = folder_graph_build(kv)
+        assert result == {'nodes': [], 'edges': []}
+
+
+class TestGraphNodes:
+    def test_one_node_per_folder(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj-a', agent='kiro')
+        add_obs(kv, '/home/user/proj-a', agent='claude')  # same folder, different agent
+        add_obs(kv, '/home/user/proj-b', agent='kiro')
+        result = folder_graph_build(kv)
+        node_ids = [n['id'] for n in result['nodes']]
+        assert len(node_ids) == len(set(node_ids))  # no duplicates
+        # 2 unique folders
+        assert len(result['nodes']) == 2
+
+    def test_node_has_required_fields(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj')
+        result = folder_graph_build(kv)
+        node = result['nodes'][0]
+        assert 'id' in node
+        assert 'label' in node
+        assert 'folderPath' in node
+        assert 'agentIds' in node
+        assert 'obsCount' in node
+        assert 'color' in node
+
+    def test_agent_ids_aggregated(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj', agent='kiro')
+        add_obs(kv, '/home/user/proj', agent='claude')
+        result = folder_graph_build(kv)
+        node = result['nodes'][0]
+        assert 'kiro' in node['agentIds']
+        assert 'claude' in node['agentIds']
+
+
+class TestGraphEdges:
+    def test_same_parent_edge(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj/src')
+        add_obs(kv, '/home/user/proj/tests')
+        result = folder_graph_build(kv)
+        same_parent = [e for e in result['edges'] if e['type'] == 'same-parent']
+        assert len(same_parent) >= 1
+
+    def test_no_duplicate_edges(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj/src')
+        add_obs(kv, '/home/user/proj/tests')
+        result = folder_graph_build(kv)
+        edge_keys = [(e['source'], e['target'], e['type']) for e in result['edges']]
+        assert len(edge_keys) == len(set(edge_keys))
+
+    def test_agent_shared_edge(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, '/home/user/proj-a', agent='kiro')
+        add_obs(kv, '/home/user/proj-b', agent='kiro')
+        result = folder_graph_build(kv)
+        agent_edges = [e for e in result['edges'] if e['type'] == 'agent-shared']
+        assert len(agent_edges) >= 1
+
+    def test_cross_ref_edge(self, tmp_path):
+        kv = make_kv(tmp_path)
+        fp_b = 'home/user/proj-b'
+        add_obs(kv, '/home/user/proj-a', text=f'Modified files in {fp_b}')
+        add_obs(kv, '/home/user/proj-b', text='Normal work')
+        result = folder_graph_build(kv)
+        cross_ref = [e for e in result['edges'] if e['type'] == 'cross-ref']
+        assert len(cross_ref) >= 1

tests/test_migration.py

@@ -0,0 +1,118 @@
+"""Unit tests for migrate_sessions_to_folders (REQ-058–REQ-062)."""
+import sys
+import os
+import pytest
+import datetime
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from db import StateKV
+from functions import migrate_sessions_to_folders, KV
+
+
+def make_kv(tmp_path):
+    db_path = os.path.join(str(tmp_path), 'test.db')
+    return StateKV(db_path=db_path)
+
+
+def seed_session(kv, session_id='sess_001', cwd='/home/user/proj', agent='kiro', obs_count=3):
+    """Seed a legacy session with observations into the old schema."""
+    ts = datetime.datetime.utcnow().isoformat() + 'Z'
+    session = {
+        'id': session_id,
+        'project': cwd,
+        'cwd': cwd,
+        'agentId': agent,
+        'startedAt': ts,
+        'updatedAt': ts,
+        'status': 'completed',
+    }
+    kv.set(KV.sessions, session_id, session)
+    obs_ids = []
+    for i in range(obs_count):
+        obs_id = f'obs_{i}'
+        obs = {
+            'id': obs_id,
+            'sessionId': session_id,
+            'timestamp': ts,
+            'type': 'file_edit',
+            'title': f'Edit {i}',
+            'narrative': f'Edited file {i}',
+            'concepts': ['python'],
+            'files': [f'src/file_{i}.py'],
+            'importance': 5,
+        }
+        kv.set(KV.observations(session_id), obs_id, obs)
+        obs_ids.append(obs_id)
+    return obs_ids
+
+
+class TestMigrateDryRun:
+    def test_dry_run_writes_nothing(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv)
+        result = migrate_sessions_to_folders(kv, dry_run=True)
+        assert result['migrated_sessions'] > 0
+        assert result['migrated_observations'] > 0
+        # No folder obs should have been written
+        fp = 'home/user/proj'
+        obs = kv.list(KV.folder_obs(fp, 'kiro'))
+        assert len(obs) == 0
+
+    def test_dry_run_returns_counts(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv, obs_count=5)
+        result = migrate_sessions_to_folders(kv, dry_run=True)
+        assert result['migrated_observations'] == 5
+        assert result['dry_run'] is True
+
+
+class TestMigrateActual:
+    def test_migrates_observations(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv, obs_count=3)
+        migrate_sessions_to_folders(kv, dry_run=False)
+        fp = 'home/user/proj'
+        obs = kv.list(KV.folder_obs(fp, 'kiro'))
+        assert len(obs) == 3
+
+    def test_skips_raw_observations(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv, obs_count=2)
+        # Add a raw obs
+        kv.set(KV.observations('sess_001'), 'obs_0:raw', {
+            'id': 'obs_0:raw', 'sessionId': 'sess_001',
+            'timestamp': datetime.datetime.utcnow().isoformat() + 'Z',
+        })
+        result = migrate_sessions_to_folders(kv, dry_run=False)
+        # Raw obs should not be counted
+        assert result['migrated_observations'] == 2
+
+    def test_nondestructive(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv)
+        migrate_sessions_to_folders(kv, dry_run=False)
+        # Old session data still there
+        session = kv.get(KV.sessions, 'sess_001')
+        assert session is not None
+
+    def test_unknown_fallback(self, tmp_path):
+        kv = make_kv(tmp_path)
+        # Session with no cwd or project
+        ts = datetime.datetime.utcnow().isoformat() + 'Z'
+        kv.set(KV.sessions, 'sess_no_path', {
+            'id': 'sess_no_path', 'startedAt': ts, 'updatedAt': ts, 'status': 'completed',
+        })
+        kv.set(KV.observations('sess_no_path'), 'obs_x', {
+            'id': 'obs_x', 'sessionId': 'sess_no_path',
+            'timestamp': ts, 'type': 'other', 'title': 'x', 'narrative': 'x',
+        })
+        result = migrate_sessions_to_folders(kv, dry_run=False)
+        # Should succeed with 'unknown' fallback
+        assert result['migrated_sessions'] >= 1
+
+    def test_returns_error_list(self, tmp_path):
+        kv = make_kv(tmp_path)
+        seed_session(kv)
+        result = migrate_sessions_to_folders(kv, dry_run=False)
+        assert 'errors' in result
+        assert isinstance(result['errors'], list)

tests/test_normalize.py

@@ -0,0 +1,60 @@
+"""Unit tests for normalize_folder_path (REQ-002, REQ-063, REQ-064, REQ-066)."""
+import sys
+import os
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from functions import normalize_folder_path
+
+
+class TestNormalizeFolderPath:
+    def test_unix_path(self):
+        assert normalize_folder_path('/home/user/projects/myapp') == 'home/user/projects/myapp'
+
+    def test_windows_path(self):
+        result = normalize_folder_path('C:\\Users\\foo\\projects\\myapp')
+        assert '\\' not in result
+        assert 'Users' in result or 'users' in result.lower()
+
+    def test_trailing_slash_stripped(self):
+        result = normalize_folder_path('/home/user/projects/')
+        assert not result.endswith('/')
+
+    def test_leading_slash_stripped(self):
+        result = normalize_folder_path('/home/user/projects')
+        assert not result.startswith('/')
+
+    def test_double_slashes_collapsed(self):
+        result = normalize_folder_path('/home//user///projects')
+        assert '//' not in result
+
+    def test_empty_string_raises(self):
+        with pytest.raises(ValueError):
+            normalize_folder_path('')
+
+    def test_path_traversal_raises(self):
+        with pytest.raises(ValueError):
+            normalize_folder_path('/home/user/../../etc/passwd')
+
+    def test_length_cap(self):
+        long_path = 'a/' * 300
+        result = normalize_folder_path(long_path)
+        assert len(result) <= 512
+
+    def test_idempotent(self):
+        path = '/home/user/projects/myapp'
+        once = normalize_folder_path(path)
+        twice = normalize_folder_path(once)
+        assert once == twice
+
+    def test_relative_path(self):
+        result = normalize_folder_path('projects/myapp/src')
+        assert result == 'projects/myapp/src'
+
+    def test_windows_forward_slashes(self):
+        result = normalize_folder_path('C:/Users/foo/projects')
+        assert '\\' not in result
+
+    def test_single_segment(self):
+        result = normalize_folder_path('/workspace')
+        assert result == 'workspace'

tests/test_timeline.py

@@ -0,0 +1,96 @@
+"""Unit tests for folder_timeline (REQ-020, REQ-021, REQ-022, REQ-071)."""
+import sys
+import os
+import pytest
+import datetime
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'src'))
+from db import StateKV
+from functions import folder_observe, folder_timeline
+
+
+def make_kv(tmp_path):
+    db_path = os.path.join(str(tmp_path), 'test.db')
+    return StateKV(db_path=db_path)
+
+
+def ts(offset_seconds=0):
+    dt = datetime.datetime(2025, 1, 15, 10, 0, 0) + datetime.timedelta(seconds=offset_seconds)
+    return dt.isoformat() + 'Z'
+
+
+def add_obs(kv, folder='/home/user/proj', agent='kiro', timestamp=None, text='obs'):
+    return folder_observe(kv, {
+        'folderPath': folder,
+        'agentId': agent,
+        'text': text,
+        'timestamp': timestamp or ts(),
+    })
+
+
+class TestTimelineOrdering:
+    def test_results_sorted_desc(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, timestamp=ts(0))
+        add_obs(kv, timestamp=ts(60))
+        add_obs(kv, timestamp=ts(30))
+        results = folder_timeline(kv)
+        timestamps = [r['timestamp'] for r in results]
+        assert timestamps == sorted(timestamps, reverse=True)
+
+    def test_empty_returns_empty(self, tmp_path):
+        kv = make_kv(tmp_path)
+        results = folder_timeline(kv)
+        assert results == []
+
+
+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))
+        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))
+        results = folder_timeline(kv)
+        assert len(results) == 100
+
+
+class TestTimelineFilters:
+    def test_folder_filter(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, folder='/home/user/proj-a', timestamp=ts(0))
+        add_obs(kv, folder='/home/user/proj-b', timestamp=ts(1))
+        results = folder_timeline(kv, folder_path='home/user/proj-a')
+        assert all(r['folderPath'] == 'home/user/proj-a' for r in results)
+        assert len(results) == 1
+
+    def test_agent_filter(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, agent='kiro', timestamp=ts(0))
+        add_obs(kv, agent='claude', timestamp=ts(1))
+        results = folder_timeline(kv, agent_id='kiro')
+        assert all(r['agentId'] == 'kiro' for r in results)
+
+    def test_before_filter(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, timestamp=ts(0))   # 10:00:00
+        add_obs(kv, timestamp=ts(60))  # 10:01:00
+        add_obs(kv, timestamp=ts(120)) # 10:02:00
+        results = folder_timeline(kv, before=ts(90))
+        # Should only include obs before 10:01:30
+        for r in results:
+            assert r['timestamp'] < ts(90)
+
+    def test_after_filter(self, tmp_path):
+        kv = make_kv(tmp_path)
+        add_obs(kv, timestamp=ts(0))
+        add_obs(kv, timestamp=ts(60))
+        add_obs(kv, timestamp=ts(120))
+        results = folder_timeline(kv, after=ts(30))
+        for r in results:
+            assert r['timestamp'] > ts(30)