fix: Added prod level migrations

.github/workflows/automation.yml

@@ -1,26 +1,13 @@
-name: Test Automation Pipeline
+name: Test & Publish Pipeline
 
 on:
   push:
     branches: [main]
-    paths-ignore:
-      - "README.md"
-      - "CHANGELOG.md"
-      - "AGENTS.md"
-      - "ROADMAP.md"
-      - "**/*.md"
+    tags:
+      - 'v*'
   pull_request:
     branches: [main]
-    paths-ignore:
-      - "README.md"
-      - "CHANGELOG.md"
-      - "AGENTS.md"
-      - "ROADMAP.md"
-      - "**/*.md"
   workflow_dispatch:
-  schedule:
-    # Run every Sunday at midnight to check for dependency updates and slow/regression bugs
-    - cron: '0 0 * * 0'
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -55,7 +42,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.10", "3.11", "3.12"]
     
     steps:
@@ -68,7 +55,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
 
-      - name: Install Dependencies
+      - name: Install Package & Dev Dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
@@ -79,7 +66,7 @@ jobs:
       - name: Run Hypothesis Property-Based Tests
         run: pytest tests/test_properties.py -v --tb=short
 
-  build-verification:
+  build-and-verify:
     name: Build & Package Verification
     needs: automated-testing
     runs-on: ubuntu-latest
@@ -92,12 +79,15 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Install Build Tool
-        run: pip install build
+      - name: Install Build and Twine
+        run: pip install build twine
 
       - name: Build Package (wheel & sdist)
         run: python -m build
 
+      - name: Verify Package Metadata
+        run: twine check dist/*
+
       - name: Upload Build Artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -105,24 +95,22 @@ jobs:
           path: dist/
           retention-days: 5
 
-  deploy-to-huggingface:
-    name: Deploy to Hugging Face Spaces
-    needs: [lint-and-format, automated-testing, build-verification]
-    if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build-and-verify
+    # Only run on pushes of version tags (e.g. v0.9.8) to the main branch
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
     steps:
-      - name: Checkout Code
-        uses: actions/checkout@v4
+      - name: Download Build Artifacts
+        uses: actions/download-artifact@v4
         with:
-          fetch-depth: 0
-          lfs: true
-
-      - name: Push to Hugging Face Space
-        env:
-          HF_TOKEN: ${{ secrets.HF_TOKEN }}
-        run: |
-          git config --global user.email "bot@github.com"
-          git config --global user.name "GitHub Action Bot"
-          git remote add hf https://Yash030:$HF_TOKEN@huggingface.co/spaces/Yash030/agentmemory-python
-          git push --force hf main:main
+          name: agentcache-dist
+          path: dist/
 
+      - name: Publish Package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true

Dockerfile

@@ -15,14 +15,11 @@ RUN useradd -m -u 1000 user
 # Set up workdir
 WORKDIR /app
 
-# Copy python dependencies and install
-COPY requirements.txt /app/requirements.txt
-RUN pip install --no-cache-dir -r /app/requirements.txt
-
-# Copy application files
-COPY --chown=user:user src /app/src
-COPY --chown=user:user start.sh /app/start.sh
-COPY --chown=user:user sync.py /app/sync.py
+# Copy all application files first to support package installation
+COPY --chown=user:user . /app
+
+# Install the package directly in non-editable mode for production deployment
+RUN pip install --no-cache-dir /app
 
 # Give permissions
 RUN chmod +x /app/start.sh && chown -R user:user /app /home/user

examples/antigravity_sync.py

@@ -146,7 +146,7 @@ def perform_antigravity_sync_local(args):
                             current_prompt = p_text.strip()
                             current_timestamp = step.get("created_at")
                         elif step_type == "PLANNER_RESPONSE" and current_prompt:
-                            ts = current_timestamp or step.get("created_at") or datetime.datetime.utcnow().isoformat() + "Z"
+                            ts = current_timestamp or step.get("created_at") or datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
                             turns.append({"prompt": current_prompt, "response": step.get("content", ""), "timestamp": ts})
                             current_prompt = None
                             current_timestamp = None

plugin/scripts/notification.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def main():
@@ -28,7 +28,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "notification_type": notification_type,
             "title": data.get("title"),

plugin/scripts/post_tool_failure.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def main():
@@ -34,7 +34,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "tool_name": tool_name,
             "tool_input": limit_str(tool_input),

plugin/scripts/post_tool_use.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def is_base64_image(val):
@@ -80,7 +80,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "tool_name": tool_name,
             "tool_input": tool_input,

plugin/scripts/prompt_submit.py

@@ -42,7 +42,7 @@ def main():
         "sessionId": session_id,
         "project": project,
         "cwd": cwd,
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "prompt": prompt
         }

plugin/scripts/subagent_start.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def main():
@@ -26,7 +26,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "agent_id": agent_id,
             "agent_type": agent_type

plugin/scripts/subagent_stop.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def main():
@@ -32,7 +32,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "agent_id": agent_id,
             "agent_type": agent_type,

plugin/scripts/task_completed.py

@@ -2,7 +2,7 @@
 import sys
 import json
 import time
-from datetime import datetime
+from datetime import datetime, timezone
 from hook_utils import resolve_project, is_sdk_child, api_call_bg
 
 def main():
@@ -29,7 +29,7 @@ def main():
         "sessionId": session_id,
         "project": resolve_project(data.get("cwd")),
         "cwd": data.get("cwd") or "",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         "data": {
             "task_id": data.get("task_id"),
             "task_subject": data.get("task_subject"),

pyproject.toml

@@ -7,8 +7,26 @@ name = "agentcache"
 version = "0.9.8"
 description = "A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite"
 readme = "README.md"
+authors = [
+    { name = "Yash Wanjarwadkar", email = "yashwanjarwadkar@gmail.com" }
+]
+maintainers = [
+    { name = "Yash Wanjarwadkar", email = "yashwanjarwadkar@gmail.com" }
+]
 license = { text = "MIT" }
 requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
 dependencies = [
     "flask>=3.0.0",
     "flask-sock>=0.7.0",
@@ -22,21 +40,37 @@ dependencies = [
 dev = [
     "pytest>=8.0.0",
     "hypothesis>=6.100.0",
+    "ruff>=0.3.0",
+    "twine>=5.0.0",
 ]
 local-embeddings = [
     "sentence-transformers>=2.7.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/Yash030/agentcache-python"
+Repository = "https://github.com/Yash030/agentcache-python.git"
+"Bug Tracker" = "https://github.com/Yash030/agentcache-python/issues"
+Documentation = "https://github.com/Yash030/agentcache-python#readme"
+
 [project.scripts]
-agentcache = "src.cli:main"
+agentcache = "agentcache.cli:main"
 
 [tool.setuptools.packages.find]
-where = ["."]
-include = ["src*"]
+where = ["src"]
+include = ["agentcache*"]
 
 [tool.setuptools.package-data]
-"src.viewer" = ["*.html", "*.svg", "*.js", "*.css"]
+"agentcache.viewer" = ["*.html", "*.svg", "*.js", "*.css"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]

requirements.txt

@@ -1,10 +1 @@
-flask>=3.0.0
-flask-sock>=0.7.0
-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
+-e .[dev,local-embeddings]

src/agentcache.egg-info/PKG-INFO

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

src/agentcache.egg-info/SOURCES.txt

@@ -0,0 +1,59 @@
+LICENSE
+README.md
+pyproject.toml
+src/agentcache/__init__.py
+src/agentcache/app.py
+src/agentcache/cli.py
+src/agentcache/connect.py
+src/agentcache/db.py
+src/agentcache/functions.py
+src/agentcache/import_data.py
+src/agentcache/mcp_stdio.py
+src/agentcache/replay_import.py
+src/agentcache/search.py
+src/agentcache/viewer_helpers.py
+src/agentcache/workers.py
+src/agentcache.egg-info/PKG-INFO
+src/agentcache.egg-info/SOURCES.txt
+src/agentcache.egg-info/dependency_links.txt
+src/agentcache.egg-info/entry_points.txt
+src/agentcache.egg-info/requires.txt
+src/agentcache.egg-info/top_level.txt
+src/agentcache/cache/__init__.py
+src/agentcache/cache/context.py
+src/agentcache/cache/graph.py
+src/agentcache/cache/health.py
+src/agentcache/cache/observe.py
+src/agentcache/cache/remember.py
+src/agentcache/cache/timeline.py
+src/agentcache/routes/__init__.py
+src/agentcache/routes/graph.py
+src/agentcache/routes/health.py
+src/agentcache/routes/mcp.py
+src/agentcache/routes/memories.py
+src/agentcache/routes/migration.py
+src/agentcache/routes/observations.py
+src/agentcache/routes/search.py
+src/agentcache/storage/__init__.py
+src/agentcache/storage/images.py
+src/agentcache/storage/paths.py
+src/agentcache/storage/scopes.py
+src/agentcache/viewer/favicon.svg
+src/agentcache/viewer/index.html
+tests/test_api.py
+tests/test_auth.py
+tests/test_context.py
+tests/test_debounce.py
+tests/test_folder_graph_build.py
+tests/test_folder_observe.py
+tests/test_forget.py
+tests/test_graph.py
+tests/test_migration.py
+tests/test_normalize.py
+tests/test_obs_lookup.py
+tests/test_observe_core.py
+tests/test_properties.py
+tests/test_remember.py
+tests/test_route_regressions.py
+tests/test_search.py
+tests/test_timeline.py

src/agentcache.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

src/agentcache.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentcache = agentcache.cli:main

src/agentcache.egg-info/requires.txt

@@ -0,0 +1,15 @@
+flask>=3.0.0
+flask-sock>=0.7.0
+requests>=2.31.0
+python-dateutil>=2.8.2
+huggingface_hub>=0.20.0
+websockets>=12.0
+
+[dev]
+pytest>=8.0.0
+hypothesis>=6.100.0
+ruff>=0.3.0
+twine>=5.0.0
+
+[local-embeddings]
+sentence-transformers>=2.7.0

src/agentcache.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentcache

src/agentcache/__init__.py

@@ -0,0 +1,32 @@
+"""
+agentcache — A Python REST + WebSocket + MCP cache server for AI agents, backed by SQLite.
+"""
+
+__version__ = "0.9.8"
+
+from .app import create_app
+from .connect import run_connect
+from .db import StateKV
+from .functions import (
+    folder_graph_build,
+    folder_observe,
+    folder_search,
+    folder_timeline,
+    forget,
+    health_check,
+    remember,
+)
+
+__all__ = [
+    "__version__",
+    "create_app",
+    "StateKV",
+    "run_connect",
+    "folder_observe",
+    "folder_search",
+    "folder_timeline",
+    "folder_graph_build",
+    "remember",
+    "forget",
+    "health_check",
+]

src/{app.py → agentcache/app.py}

@@ -1,280 +1,284 @@
-"""
-agentmemory-python — Flask application factory.
-
-Entry point: create_app() returns a fully configured Flask app.
-Run directly:  python src/app.py
-"""
-
-import os
-import sys
-import json
-import hmac
-from flask import Flask, request, send_from_directory
-from flask_sock import Sock
-
-# Prevent double-import of app when run directly as __main__
-if __name__ == "__main__":
-    sys.modules["app"] = sys.modules["__main__"]
-
-
-def _load_env() -> None:
-    env_path = os.path.join(os.path.expanduser("~"), ".agentcache", ".env")
-    if not os.path.exists(env_path):
-        env_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".env")
-    if not os.path.exists(env_path):
-        return
-    try:
-        with open(env_path, "r", encoding="utf-8") as f:
-            for line in f:
-                line = line.strip()
-                if not line or line.startswith("#") or "=" not in line:
-                    continue
-                k, v = line.split("=", 1)
-                os.environ[k.strip()] = v.strip().strip('"').strip("'")
-        print(f"[config] Loaded environment from {env_path}")
-    except Exception as e:
-        print(f"[config] Error reading env file: {e}")
-
-
-_load_env()
-
-# Module-level globals — set once by create_app(), read by blueprints via `import app`
-kv = None
-embedding_provider = None
-persistence = None
-
-
-def create_app() -> Flask:
-    """Create and return a fully configured Flask application."""
-    global kv, embedding_provider, persistence
-
-    # Check security credentials
-    if not os.getenv("AGENTCACHE_SECRET") and not os.getenv("AGENTMEMORY_SECRET"):
-        print(
-            "[security] WARNING: AGENTCACHE_SECRET/AGENTMEMORY_SECRET is not set! All API endpoints are publicly accessible without authentication."
-        )
-
-    import search as search_mod
-    import functions
-    from db import StateKV
-    from viewer_helpers import make_viewer_response
-
-    # 1. DB
-    kv = StateKV()
-
-    # 2. Embedding provider — auto-select by priority (D5.3):
-    #    GEMINI_API_KEY → OPENAI_API_KEY → AGENTCACHE_LOCAL_EMBEDDING_MODEL → BM25-only
-    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
-    openai_key = os.getenv("OPENAI_API_KEY")
-    local_model = os.getenv("AGENTCACHE_LOCAL_EMBEDDING_MODEL") or os.getenv(
-        "AGENTMEMORY_LOCAL_EMBEDDING_MODEL"
-    )
-
-    if api_key:
-        try:
-            embedding_provider = search_mod.GeminiEmbeddingProvider(api_key)
-            functions.set_embedding_provider(embedding_provider)
-            print(
-                f"[search] Embedding provider active: gemini ({embedding_provider.dimensions} dims)"
-            )
-        except Exception as e:
-            print(f"[search] Error initialising Gemini embedding provider: {e}")
-    elif openai_key:
-        try:
-            embedding_provider = search_mod.OpenAIEmbeddingProvider(openai_key)
-            functions.set_embedding_provider(embedding_provider)
-            print(
-                f"[search] Embedding provider active: openai ({embedding_provider.dimensions} dims)"
-            )
-        except Exception as e:
-            print(f"[search] Error initialising OpenAI embedding provider: {e}")
-    elif local_model:
-        try:
-            embedding_provider = search_mod.SentenceTransformerProvider(local_model)
-            functions.set_embedding_provider(embedding_provider)
-            print(
-                f"[search] Embedding provider active: sentence-transformers/{local_model} ({embedding_provider.dimensions} dims)"
-            )
-        except ImportError as e:
-            print(f"[search] sentence-transformers not installed: {e}")
-        except Exception as e:
-            print(f"[search] Error initialising SentenceTransformer provider: {e}")
-    else:
-        print("[search] No embedding API key found — running in BM25-only mode.")
-
-    # 3. Index persistence — use embedding_provider variable set above
-    has_vector = embedding_provider is not None
-    persistence = functions.IndexPersistence(
-        kv,
-        functions._bm25_index,
-        functions._vector_index if has_vector else None,
-    )
-    functions.set_index_persistence(persistence)
-    loaded = persistence.load()
-    print(
-        f"[persistence] Load results: BM25={loaded['bm25']}, Vector={loaded['vector']}"
-    )
-
-    # Backfill coordinate lookup index if missing/incomplete
-    try:
-        functions.backfill_obs_lookup_if_needed(kv)
-    except Exception as e:
-        print(f"[db] Warning backfilling obs_lookup: {e}")
-
-    # 4. Flask app + blueprints
-    flask_app = Flask(__name__)
-    from werkzeug.middleware.proxy_fix import ProxyFix
-
-    flask_app.wsgi_app = ProxyFix(
-        flask_app.wsgi_app, x_proto=1, x_host=1, x_port=1, x_prefix=1
-    )
-    from routes import register_blueprints
-
-    register_blueprints(flask_app)
-
-    # 5. WebSocket broadcaster
-    sock = Sock(flask_app)
-    _ws_clients: set = set()
-
-    @sock.route("/stream/mem-live/viewer")
-    def stream_viewer(ws):
-        secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
-        if secret:
-            token = request.args.get("token") or request.args.get("secret")
-            if not token or not hmac.compare_digest(
-                token.encode("utf-8"), secret.encode("utf-8")
-            ):
-                ws.close(1008)
-                return
-        _ws_clients.add(ws)
-        try:
-            while ws.receive() is not None:
-                pass
-        except Exception:
-            pass
-        finally:
-            _ws_clients.discard(ws)
-
-    def _broadcast(payload: dict) -> None:
-        msg = json.dumps(payload)
-        for ws in list(_ws_clients):
-            try:
-                ws.send(msg)
-            except Exception:
-                _ws_clients.discard(ws)
-
-    functions.set_stream_broadcaster(_broadcast)
-
-    # 6. Viewer static routes
-    _base_dir = os.path.dirname(os.path.abspath(__file__))
-
-    @flask_app.route("/")
-    @flask_app.route("/viewer")
-    @flask_app.route("/agentcache/viewer")
-    @flask_app.route("/agentmemory/viewer")
-    def serve_viewer():
-        try:
-            return make_viewer_response(_base_dir)
-        except Exception as e:
-            return f"Viewer not found: {e}", 404
-
-    @flask_app.route("/favicon.svg")
-    def serve_favicon():
-        return send_from_directory(os.path.join(_base_dir, "viewer"), "favicon.svg")
-
-    # 7. CORS after_request — D2.1: configurable via AGENTCACHE_CORS_ORIGINS env var
-    # Default allows localhost, 127.0.0.1, HuggingFace Spaces, vscode-webview://, chrome-extension://
-    # Wildcard entries like "*.hf.space" match any subdomain via suffix check.
-    _default_cors = (
-        "http://localhost,http://127.0.0.1,"
-        "https://huggingface.co,https://*.hf.space,"
-        "vscode-webview://*,chrome-extension://*"
-    )
-    _cors_origins_raw = (
-        os.getenv("AGENTCACHE_CORS_ORIGINS")
-        or os.getenv("AGENTMEMORY_CORS_ORIGINS")
-        or _default_cors
-    )
-
-    def _parse_cors_origins(raw: str):
-        """Return (exact_set, suffix_list) for efficient origin matching."""
-        exact, suffixes = set(), []
-        for entry in raw.split(","):
-            entry = entry.strip()
-            if not entry:
-                continue
-            if entry.startswith("*."):
-                # *.hf.space → match anything ending with .hf.space
-                suffixes.append(entry[1:].lower())  # keep the leading dot: ".hf.space"
-            elif "*" in entry:
-                # generic prefix wildcard: strip trailing * and treat as prefix
-                suffixes.append(("prefix:", entry.rstrip("*").lower()))
-            else:
-                exact.add(entry.lower())
-        return exact, suffixes
-
-    _cors_exact, _cors_suffixes = _parse_cors_origins(_cors_origins_raw)
-
-    def _origin_allowed(origin: str) -> bool:
-        lo = origin.lower()
-        if lo in _cors_exact:
-            return True
-        for s in _cors_suffixes:
-            if isinstance(s, tuple) and s[0] == "prefix:":
-                if lo.startswith(s[1]):
-                    return True
-            elif lo.endswith(s):
-                return True
-        return False
-
-    @flask_app.after_request
-    def _cors(response):
-        origin = request.headers.get("Origin")
-        if origin and _origin_allowed(origin):
-            response.headers["Access-Control-Allow-Origin"] = origin
-            response.headers["Access-Control-Allow-Credentials"] = "true"
-        response.headers.add(
-            "Access-Control-Allow-Headers", "Content-Type, Authorization"
-        )
-        response.headers.add(
-            "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS"
-        )
-        return response
-
-    # Handle CORS preflight OPTIONS requests globally
-    from flask import Response as _FlaskResponse
-
-    @flask_app.before_request
-    def _handle_options():
-        if request.method == "OPTIONS":
-            origin = request.headers.get("Origin", "")
-            if origin and _origin_allowed(origin):
-                resp = _FlaskResponse("", status=204)
-                resp.headers["Access-Control-Allow-Origin"] = origin
-                resp.headers["Access-Control-Allow-Credentials"] = "true"
-                resp.headers["Access-Control-Allow-Headers"] = (
-                    "Content-Type, Authorization"
-                )
-                resp.headers["Access-Control-Allow-Methods"] = (
-                    "GET, POST, PUT, DELETE, OPTIONS"
-                )
-                resp.headers["Access-Control-Max-Age"] = "86400"
-                return resp
-
-    # 8. Background workers
-    from workers import start_background_workers
-
-    start_background_workers(kv)
-
-    return flask_app
-
-
-def main() -> None:
-    flask_app = create_app()
-    port = int(os.getenv("III_REST_PORT", os.getenv("PORT", "3111")))
-    print(f"[main] Starting Flask daemon on port {port}...")
-    flask_app.run(host="0.0.0.0", port=port, debug=False)
-
-
-if __name__ == "__main__":
-    main()
+"""
+agentmemory-python — Flask application factory.
+
+Entry point: create_app() returns a fully configured Flask app.
+Run directly:  python src/app.py
+"""
+
+import hmac
+import json
+import os
+import sys
+
+from flask import Flask, request, send_from_directory
+from flask_sock import Sock
+
+# Prevent double-import of app when run directly as __main__
+if __name__ == "__main__":
+    sys.modules["app"] = sys.modules["__main__"]
+
+
+def _load_env() -> None:
+    env_path = os.path.join(os.path.expanduser("~"), ".agentcache", ".env")
+    if not os.path.exists(env_path):
+        env_path = os.path.join(os.path.expanduser("~"), ".agentmemory", ".env")
+    if not os.path.exists(env_path):
+        return
+    try:
+        with open(env_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                k, v = line.split("=", 1)
+                os.environ[k.strip()] = v.strip().strip('"').strip("'")
+        print(f"[config] Loaded environment from {env_path}")
+    except Exception as e:
+        print(f"[config] Error reading env file: {e}")
+
+
+_load_env()
+
+# Module-level globals — set once by create_app(), read by blueprints via `import app`
+kv = None
+embedding_provider = None
+persistence = None
+
+
+def create_app() -> Flask:
+    """Create and return a fully configured Flask application."""
+    global kv, embedding_provider, persistence
+
+    # Check security credentials
+    if not os.getenv("AGENTCACHE_SECRET") and not os.getenv("AGENTMEMORY_SECRET"):
+        print(
+            "[security] WARNING: AGENTCACHE_SECRET/AGENTMEMORY_SECRET is not set! All API endpoints are publicly accessible without authentication."
+        )
+
+    from . import functions
+    from . import search as search_mod
+    from .db import StateKV
+    from .viewer_helpers import make_viewer_response
+
+    # 1. DB
+    kv = StateKV()
+
+    # 2. Embedding provider — auto-select by priority (D5.3):
+    #    GEMINI_API_KEY → OPENAI_API_KEY → AGENTCACHE_LOCAL_EMBEDDING_MODEL → BM25-only
+    api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
+    openai_key = os.getenv("OPENAI_API_KEY")
+    local_model = os.getenv("AGENTCACHE_LOCAL_EMBEDDING_MODEL") or os.getenv(
+        "AGENTMEMORY_LOCAL_EMBEDDING_MODEL"
+    )
+
+    if api_key:
+        try:
+            embedding_provider = search_mod.GeminiEmbeddingProvider(api_key)
+            functions.set_embedding_provider(embedding_provider)
+            print(
+                f"[search] Embedding provider active: gemini ({embedding_provider.dimensions} dims)"
+            )
+        except Exception as e:
+            print(f"[search] Error initialising Gemini embedding provider: {e}")
+    elif openai_key:
+        try:
+            embedding_provider = search_mod.OpenAIEmbeddingProvider(openai_key)
+            functions.set_embedding_provider(embedding_provider)
+            print(
+                f"[search] Embedding provider active: openai ({embedding_provider.dimensions} dims)"
+            )
+        except Exception as e:
+            print(f"[search] Error initialising OpenAI embedding provider: {e}")
+    elif local_model:
+        try:
+            embedding_provider = search_mod.SentenceTransformerProvider(local_model)
+            functions.set_embedding_provider(embedding_provider)
+            print(
+                f"[search] Embedding provider active: sentence-transformers/{local_model} ({embedding_provider.dimensions} dims)"
+            )
+        except ImportError as e:
+            print(f"[search] sentence-transformers not installed: {e}")
+        except Exception as e:
+            print(f"[search] Error initialising SentenceTransformer provider: {e}")
+    else:
+        print("[search] No embedding API key found — running in BM25-only mode.")
+
+    # 3. Index persistence — use embedding_provider variable set above
+    has_vector = embedding_provider is not None
+    persistence = functions.IndexPersistence(
+        kv,
+        functions._bm25_index,
+        functions._vector_index if has_vector else None,
+    )
+    functions.set_index_persistence(persistence)
+    loaded = persistence.load()
+    print(
+        f"[persistence] Load results: BM25={loaded['bm25']}, Vector={loaded['vector']}"
+    )
+
+    # Backfill coordinate lookup index if missing/incomplete
+    try:
+        functions.backfill_obs_lookup_if_needed(kv)
+    except Exception as e:
+        print(f"[db] Warning backfilling obs_lookup: {e}")
+
+    # 4. Flask app + blueprints
+    flask_app = Flask(__name__)
+    from werkzeug.middleware.proxy_fix import ProxyFix
+
+    flask_app.wsgi_app = ProxyFix(
+        flask_app.wsgi_app, x_proto=1, x_host=1, x_port=1, x_prefix=1
+    )
+    from .routes import register_blueprints
+
+    register_blueprints(flask_app)
+
+    # 5. WebSocket broadcaster
+    sock = Sock(flask_app)
+    _ws_clients: set = set()
+
+    @sock.route("/stream/mem-live/viewer")
+    def stream_viewer(ws):
+        secret = os.getenv("AGENTCACHE_SECRET") or os.getenv("AGENTMEMORY_SECRET")
+        if secret:
+            token = request.args.get("token") or request.args.get("secret")
+            if not token or not hmac.compare_digest(
+                token.encode("utf-8"), secret.encode("utf-8")
+            ):
+                ws.close(1008)
+                return
+        _ws_clients.add(ws)
+        try:
+            while ws.receive() is not None:
+                pass
+        except Exception:
+            pass
+        finally:
+            _ws_clients.discard(ws)
+
+    def _broadcast(payload: dict) -> None:
+        msg = json.dumps(payload)
+        for ws in list(_ws_clients):
+            try:
+                ws.send(msg)
+            except Exception:
+                _ws_clients.discard(ws)
+
+    functions.set_stream_broadcaster(_broadcast)
+
+    # 6. Viewer static routes
+    from importlib.resources import files
+
+    _viewer_resources = files("agentcache").joinpath("viewer")
+    _base_dir = str(_viewer_resources.parent)
+
+    @flask_app.route("/")
+    @flask_app.route("/viewer")
+    @flask_app.route("/agentcache/viewer")
+    @flask_app.route("/agentmemory/viewer")
+    def serve_viewer():
+        try:
+            return make_viewer_response(_base_dir)
+        except Exception as e:
+            return f"Viewer not found: {e}", 404
+
+    @flask_app.route("/favicon.svg")
+    def serve_favicon():
+        return send_from_directory(str(_viewer_resources), "favicon.svg")
+
+    # 7. CORS after_request — D2.1: configurable via AGENTCACHE_CORS_ORIGINS env var
+    # Default allows localhost, 127.0.0.1, HuggingFace Spaces, vscode-webview://, chrome-extension://
+    # Wildcard entries like "*.hf.space" match any subdomain via suffix check.
+    _default_cors = (
+        "http://localhost,http://127.0.0.1,"
+        "https://huggingface.co,https://*.hf.space,"
+        "vscode-webview://*,chrome-extension://*"
+    )
+    _cors_origins_raw = (
+        os.getenv("AGENTCACHE_CORS_ORIGINS")
+        or os.getenv("AGENTMEMORY_CORS_ORIGINS")
+        or _default_cors
+    )
+
+    def _parse_cors_origins(raw: str):
+        """Return (exact_set, suffix_list) for efficient origin matching."""
+        exact, suffixes = set(), []
+        for entry in raw.split(","):
+            entry = entry.strip()
+            if not entry:
+                continue
+            if entry.startswith("*."):
+                # *.hf.space → match anything ending with .hf.space
+                suffixes.append(entry[1:].lower())  # keep the leading dot: ".hf.space"
+            elif "*" in entry:
+                # generic prefix wildcard: strip trailing * and treat as prefix
+                suffixes.append(("prefix:", entry.rstrip("*").lower()))
+            else:
+                exact.add(entry.lower())
+        return exact, suffixes
+
+    _cors_exact, _cors_suffixes = _parse_cors_origins(_cors_origins_raw)
+
+    def _origin_allowed(origin: str) -> bool:
+        lo = origin.lower()
+        if lo in _cors_exact:
+            return True
+        for s in _cors_suffixes:
+            if isinstance(s, tuple) and s[0] == "prefix:":
+                if lo.startswith(s[1]):
+                    return True
+            elif lo.endswith(s):
+                return True
+        return False
+
+    @flask_app.after_request
+    def _cors(response):
+        origin = request.headers.get("Origin")
+        if origin and _origin_allowed(origin):
+            response.headers["Access-Control-Allow-Origin"] = origin
+            response.headers["Access-Control-Allow-Credentials"] = "true"
+        response.headers.add(
+            "Access-Control-Allow-Headers", "Content-Type, Authorization"
+        )
+        response.headers.add(
+            "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS"
+        )
+        return response
+
+    # Handle CORS preflight OPTIONS requests globally
+    from flask import Response as _FlaskResponse
+
+    @flask_app.before_request
+    def _handle_options():
+        if request.method == "OPTIONS":
+            origin = request.headers.get("Origin", "")
+            if origin and _origin_allowed(origin):
+                resp = _FlaskResponse("", status=204)
+                resp.headers["Access-Control-Allow-Origin"] = origin
+                resp.headers["Access-Control-Allow-Credentials"] = "true"
+                resp.headers["Access-Control-Allow-Headers"] = (
+                    "Content-Type, Authorization"
+                )
+                resp.headers["Access-Control-Allow-Methods"] = (
+                    "GET, POST, PUT, DELETE, OPTIONS"
+                )
+                resp.headers["Access-Control-Max-Age"] = "86400"
+                return resp
+
+    # 8. Background workers
+    from .workers import start_background_workers
+
+    start_background_workers(kv)
+
+    return flask_app
+
+
+def main() -> None:
+    flask_app = create_app()
+    port = int(os.getenv("III_REST_PORT", os.getenv("PORT", "3111")))
+    print(f"[main] Starting Flask daemon on port {port}...")
+    flask_app.run(host="0.0.0.0", port=port, debug=False)
+
+
+if __name__ == "__main__":
+    main()

src/{cache → agentcache/cache}/__init__.py

@@ -13,24 +13,23 @@ Compatibility shim: also re-exports everything from functions.py that
 callers may import from this package (A2.2).
 """
 
-from .observe import (
-    folder_observe,
-    observe,
-    build_synthetic_compression,
-    strip_private_data,
-)
-from .remember import remember, forget, jaccard_similarity
-from .context import context, export_data, rebuild_index
-from .graph import folder_graph_build
-from .timeline import folder_timeline, folder_search
-from .health import health_check, auto_forget
-
 # ---------------------------------------------------------------------------
 # Compatibility shim — delegate additional names to functions.py (A2.2)
 # Each name is imported lazily via a try/except so missing items don't break
 # the package import on partially-initialised environments.
 # ---------------------------------------------------------------------------
-import functions as _fn  # noqa: E402  (functions.py is on sys.path via src/)
+from .. import functions as _fn  # noqa: E402
+from .context import context, export_data, rebuild_index
+from .graph import folder_graph_build
+from .health import auto_forget, health_check
+from .observe import (
+    build_synthetic_compression,
+    folder_observe,
+    observe,
+    strip_private_data,
+)
+from .remember import forget, jaccard_similarity, remember
+from .timeline import folder_search, folder_timeline
 
 KV = _fn.KV
 generate_id = _fn.generate_id

src/{cache → agentcache/cache}/context.py

@@ -11,8 +11,8 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from db import StateKV
-import functions as _fn
+from .. import functions as _fn
+from ..db import StateKV
 
 
 def context(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:

src/{cache → agentcache/cache}/graph.py

@@ -9,8 +9,8 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from db import StateKV
-import functions as _fn
+from .. import functions as _fn
+from ..db import StateKV
 
 
 def folder_graph_build(kv: StateKV) -> Dict[str, Any]:

src/{cache → agentcache/cache}/health.py

@@ -10,8 +10,8 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from db import StateKV
-import functions as _fn
+from .. import functions as _fn
+from ..db import StateKV
 
 
 def health_check(kv: StateKV) -> Dict[str, Any]:

src/{cache → agentcache/cache}/observe.py

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

src/{cache → agentcache/cache}/remember.py

@@ -11,8 +11,8 @@ from __future__ import annotations
 
 from typing import Any, Dict
 
-from db import StateKV
-import functions as _fn
+from .. import functions as _fn
+from ..db import StateKV
 
 
 def remember(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:

src/{cache → agentcache/cache}/timeline.py

@@ -10,8 +10,8 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
-from db import StateKV
-import functions as _fn
+from .. import functions as _fn
+from ..db import StateKV
 
 
 def folder_timeline(

src/{cli.py → agentcache/cli.py}

@@ -11,14 +11,12 @@ Commands:
 import argparse
 import json
 import os
-import sys
 
 
 def cmd_serve(args) -> None:
     """Start the Flask server."""
     os.environ.setdefault("III_REST_PORT", str(args.port))
-    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-    from app import create_app
+    from .app import create_app
 
     flask_app = create_app()
     print(f"[cli] Starting agentcache on {args.host}:{args.port}")
@@ -27,9 +25,8 @@ def cmd_serve(args) -> None:
 
 def cmd_migrate(args) -> None:
     """Run session → folder migration."""
-    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-    from db import StateKV
-    from functions import migrate_sessions_to_folders
+    from .db import StateKV
+    from .functions import migrate_sessions_to_folders
 
     kv = StateKV()
     result = migrate_sessions_to_folders(kv, dry_run=args.dry_run)
@@ -54,9 +51,8 @@ def cmd_migrate(args) -> None:
 
 def cmd_export(args) -> None:
     """Export all data as JSON."""
-    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-    from db import StateKV
-    from functions import export_data
+    from .db import StateKV
+    from .functions import export_data
 
     kv = StateKV()
     data = export_data(kv, {})
@@ -78,8 +74,7 @@ def cmd_export(args) -> None:
 
 def cmd_connect(args) -> None:
     """Connect/wire MCP and hooks to client agents."""
-    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-    from connect import run_connect
+    from .connect import run_connect
 
     run_connect(args)
 

src/{connect.py → agentcache/connect.py}

@@ -1,9 +1,9 @@
 #!/usr/bin/env python3
-import os
-import sys
+import argparse
 import json
+import os
 import shutil
-import argparse
+import sys
 
 # Helper functions for connect module
 
@@ -45,9 +45,9 @@ def backup_file(path, prefix, ext="json"):
 
 
 def get_plugin_root():
-    # connect.py resides in src/, plugin/ is in the parent directory
+    # connect.py resides in src/agentcache/, plugin/ is in the parent of src/
     src_dir = os.path.dirname(os.path.abspath(__file__))
-    project_root = os.path.dirname(src_dir)
+    project_root = os.path.dirname(os.path.dirname(src_dir))
     plugin_path = os.path.join(project_root, "plugin")
     if os.path.exists(os.path.join(plugin_path, "scripts")):
         return plugin_path
@@ -368,14 +368,7 @@ class AntigravityAdapter:
         os.makedirs(gemini_mcp_dir, exist_ok=True)
         try:
             # Dynamic import to avoid circular dependency
-            try:
-                from routes.mcp import get_mcp_tools_schemas
-            except ImportError:
-                try:
-                    from src.routes.mcp import get_mcp_tools_schemas
-                except ImportError:
-                    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-                    from routes.mcp import get_mcp_tools_schemas
+            from .routes.mcp import get_mcp_tools_schemas
 
             tools = get_mcp_tools_schemas()
         except Exception as e:

src/{db.py → agentcache/db.py}

@@ -1,10 +1,10 @@
-import os
+import atexit
 import json
+import os
 import sqlite3
 import threading
 import time
-import atexit
-from typing import Dict, Any, List, Optional, TypeVar
+from typing import Any, Dict, List, Optional, TypeVar
 
 T = TypeVar("T")
 

src/{functions.py → agentcache/functions.py}

@@ -1,14 +1,15 @@
+import datetime
+import hashlib
+import json
 import os
 import re
+import threading
 import time
 import uuid
-import json
-import hashlib
-import datetime
-import threading
-from typing import Dict, Any, List, Optional, Tuple, Set
-from db import StateKV
-from search import SearchIndex, VectorIndex, HybridSearch
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from .db import StateKV
+from .search import HybridSearch, SearchIndex, VectorIndex
 
 # =====================================================================
 # Global Variables / Module State
@@ -253,7 +254,9 @@ def auto_complete_old_active_sessions(
 ) -> int:
     sessions = kv.list(KV.sessions)
     count = 0
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     for s in sessions:
         if s.get("id") != current_session_id and s.get("status") == "active":
             if project and s.get("project") != project:
@@ -337,7 +340,9 @@ def record_audit(
 ) -> Dict[str, Any]:
     entry = {
         "id": generate_id("aud"),
-        "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.datetime.now(datetime.timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z"),
         "operation": operation,
         "userId": user_id,
         "functionId": function_id,
@@ -1009,7 +1014,9 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
             {
                 "type": "set",
                 "path": "updatedAt",
-                "value": datetime.datetime.utcnow().isoformat() + "Z",
+                "value": datetime.datetime.now(datetime.timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z"),
             },
             {
                 "type": "set",
@@ -1035,7 +1042,11 @@ def observe(kv: StateKV, payload: Dict[str, Any]) -> Dict[str, Any]:
         trimmed_prompt = None
         if isinstance(raw.get("userPrompt"), str):
             trimmed_prompt = " ".join(raw["userPrompt"].split()).strip()[:200]
-        ts = datetime.datetime.utcnow().isoformat() + "Z"
+        ts = (
+            datetime.datetime.now(datetime.timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z")
+        )
         new_sess = {
             "id": session_id,
             "project": project,
@@ -1600,7 +1611,9 @@ def remember(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     if project:
         project = project.strip()
 
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     existing_memories = kv.list(KV.memories)
     superseded_id = None
     superseded_version = 1
@@ -1645,8 +1658,10 @@ def remember(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         new_mem["project"] = project
 
     if ttl_days and isinstance(ttl_days, (int, float)) and ttl_days > 0:
-        forget_time = datetime.datetime.utcnow() + datetime.timedelta(days=ttl_days)
-        new_mem["forgetAfter"] = forget_time.isoformat() + "Z"
+        forget_time = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(
+            days=ttl_days
+        )
+        new_mem["forgetAfter"] = forget_time.isoformat().replace("+00:00", "Z")
 
     if superseded_memory:
         superseded_memory["isLatest"] = False
@@ -2164,7 +2179,9 @@ DEFAULT_SLOTS = [
 
 
 def seed_defaults(kv: StateKV) -> None:
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     for tmpl in DEFAULT_SLOTS:
         scope = tmpl["scope"]
         target = KV.globalSlots if scope == "global" else KV.slots
@@ -2265,7 +2282,9 @@ def slot_create(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     if existing:
         return {"success": False, "error": f"slot already exists in {scope} scope"}
 
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     slot = {
         "label": label,
         "content": content,
@@ -2327,7 +2346,9 @@ def slot_append(
         }
 
     slot["content"] = next_content
-    slot["updatedAt"] = datetime.datetime.utcnow().isoformat() + "Z"
+    slot["updatedAt"] = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     kv.set(target_kv, label, slot)
 
     safe_audit(
@@ -2375,7 +2396,9 @@ def slot_replace(
 
     before_len = len(slot.get("content") or "")
     slot["content"] = content
-    slot["updatedAt"] = datetime.datetime.utcnow().isoformat() + "Z"
+    slot["updatedAt"] = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     kv.set(target_kv, label, slot)
 
     safe_audit(
@@ -2455,7 +2478,9 @@ def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, A
             files.add(f)
 
     applied = 0
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
 
     if pending_lines:
         res = slot_get(kv, "pending_items", project)
@@ -2558,7 +2583,9 @@ def slot_reflect(kv: StateKV, session_id: str, max_obs: int = 50) -> Dict[str, A
 
 
 def reinforce_lesson(lesson: Dict[str, Any]) -> None:
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     lesson["reinforcements"] = lesson.get("reinforcements", 0) + 1
     conf = lesson.get("confidence", 0.5)
     lesson["confidence"] = min(1.0, conf + 0.1 * (1 - conf))
@@ -2595,7 +2622,9 @@ def lesson_save(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     if not isinstance(confidence, (int, float)) or confidence < 0 or confidence > 1:
         confidence = 0.5
 
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     lesson = {
         "id": fp,
         "content": content.strip(),
@@ -2676,7 +2705,7 @@ def lesson_recall(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
         dt = dateutil.parser.parse(baseline)
         days = (
-            datetime.datetime.utcnow().replace(tzinfo=datetime.timezone.utc)
+            datetime.datetime.now(datetime.timezone.utc)
             - dt.replace(tzinfo=datetime.timezone.utc)
         ).total_seconds() / (3600 * 24)
         recency_boost = 1 / (1 + days * 0.01)
@@ -2721,8 +2750,8 @@ def lesson_decay_sweep(kv: StateKV) -> Dict[str, Any]:
     all_lessons = kv.list(KV.lessons)
     decayed = 0
     soft_deleted = 0
-    now = datetime.datetime.utcnow()
-    timestamp = now.isoformat() + "Z"
+    now = datetime.datetime.now(datetime.timezone.utc)
+    timestamp = now.isoformat().replace("+00:00", "Z")
 
     for les in all_lessons:
         if les.get("deleted"):
@@ -2733,10 +2762,9 @@ def lesson_decay_sweep(kv: StateKV) -> Dict[str, Any]:
         import dateutil.parser
 
         dt = dateutil.parser.parse(baseline_str)
-        weeks = (
-            now.replace(tzinfo=datetime.timezone.utc)
-            - dt.replace(tzinfo=datetime.timezone.utc)
-        ).total_seconds() / (3600 * 24 * 7)
+        weeks = (now - dt.replace(tzinfo=datetime.timezone.utc)).total_seconds() / (
+            3600 * 24 * 7
+        )
         if weeks < 1.0:
             continue
 
@@ -2911,7 +2939,9 @@ def create_session(kv: StateKV, session: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def end_session(kv: StateKV, session_id: str) -> bool:
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     kv.update(
         KV.sessions,
         session_id,
@@ -2972,7 +3002,9 @@ def get_project_profile(kv: StateKV, project: str) -> Dict[str, Any]:
             "topFiles": [],
             "conventions": [],
             "commonErrors": [],
-            "updatedAt": datetime.datetime.utcnow().isoformat() + "Z",
+            "updatedAt": datetime.datetime.now(datetime.timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z"),
         }
     if not prof.get("topConcepts") and not prof.get("topFiles"):
         prof = build_project_profile(kv, project)
@@ -2988,14 +3020,16 @@ def build_project_profile(kv: StateKV, project: str) -> Dict[str, Any]:
             "topFiles": [],
             "conventions": [],
             "commonErrors": [],
-            "updatedAt": datetime.datetime.utcnow().isoformat() + "Z",
+            "updatedAt": datetime.datetime.now(datetime.timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z"),
         }
 
     # Stored profile may lack topConcepts/topFiles — compute from observations + memories if empty
     if not prof.get("topConcepts") and not prof.get("topFiles"):
-        import re as _re
         import json as _j
         import os.path as _osp
+        import re as _re
         from collections import Counter
 
         sessions = kv.list(KV.sessions)
@@ -3087,7 +3121,9 @@ def export_data(kv: StateKV, data: Optional[Dict[str, Any]] = None) -> Dict[str,
     if data is None:
         data = {}
 
-    exported_at = datetime.datetime.utcnow().isoformat() + "Z"
+    exported_at = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
 
     # ---- v2 folder-based export (primary path) ----
     folder_pairs = kv.list(KV.folders)
@@ -3226,7 +3262,9 @@ def migrate_sessions_to_folders(kv: StateKV, dry_run: bool = False) -> Dict[str,
 def set_project_profile(
     kv: StateKV, project: str, profile: Dict[str, Any]
 ) -> Dict[str, Any]:
-    profile["updatedAt"] = datetime.datetime.utcnow().isoformat() + "Z"
+    profile["updatedAt"] = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     kv.set(KV.profiles, project, profile)
 
     # Commit to Dolt
@@ -3245,7 +3283,9 @@ def add_relation(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         "sourceId": data["sourceId"],
         "targetId": data["targetId"],
         "type": data["type"],
-        "createdAt": datetime.datetime.utcnow().isoformat() + "Z",
+        "createdAt": datetime.datetime.now(datetime.timezone.utc)
+        .isoformat()
+        .replace("+00:00", "Z"),
     }
     kv.set(KV.relations, rel["id"], rel)
 
@@ -3273,7 +3313,9 @@ def evolve_memory(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
     existing["isLatest"] = False
     kv.set(KV.memories, existing["id"], existing)
 
-    now = datetime.datetime.utcnow().isoformat() + "Z"
+    now = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     new_mem = dict(existing)
     new_mem["id"] = generate_id("mem")
     new_mem["content"] = new_content
@@ -3319,8 +3361,7 @@ def evolve_memory(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
 
 
 def auto_forget(kv: StateKV, dry_run: bool = False) -> Dict[str, Any]:
-    now_dt = datetime.datetime.utcnow()
-    now_dt.isoformat() + "Z"
+    now_dt = datetime.datetime.now(datetime.timezone.utc).replace(tzinfo=None)
     evicted_memories = []
     evicted_observations = []
 
@@ -3601,7 +3642,7 @@ def summarize(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         return {"success": False, "error": "no_observations"}
 
     SUMMARY_SYSTEM = """You are a session summarization assistant. Your job is to read all raw tool executions and outcomes from a coding session and produce a high-fidelity summary.
-    
+
     Output XML:
     <summary>
       <title>Concise title summarizing the session</title>
@@ -3658,7 +3699,9 @@ def summarize(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         final_summary = {
             "sessionId": session_id,
             "project": session.get("project"),
-            "createdAt": datetime.datetime.utcnow().isoformat() + "Z",
+            "createdAt": datetime.datetime.now(datetime.timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z"),
             "title": partial_summaries[0]["title"],
             "narrative": partial_summaries[0]["narrative"],
             "keyDecisions": partial_summaries[0]["keyDecisions"],
@@ -3668,7 +3711,7 @@ def summarize(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
         }
     else:
         REDUCE_SYSTEM = """You are a session summarization reducer. Reduce multiple partial chunk summaries into a single final summary.
-        
+
         Output XML:
         <summary>
           <title>Concise final title summarizing the entire session</title>
@@ -3694,7 +3737,9 @@ def summarize(kv: StateKV, data: Dict[str, Any]) -> Dict[str, Any]:
             final_summary = {
                 "sessionId": session_id,
                 "project": session.get("project"),
-                "createdAt": datetime.datetime.utcnow().isoformat() + "Z",
+                "createdAt": datetime.datetime.now(datetime.timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z"),
                 "title": get_xml_tag(cleaned, "title") or partial_summaries[0]["title"],
                 "narrative": get_xml_tag(cleaned, "narrative") or "",
                 "keyDecisions": get_xml_children(cleaned, "decisions", "decision"),
@@ -3772,7 +3817,7 @@ def consolidate(
 
     # Prompt templates
     CONSOLIDATION_SYSTEM = """You are a memory consolidation engine. Given a set of related observations from coding sessions, synthesize them into a single long-term memory.
-    
+
     Output XML:
     <memory>
       <type>pattern|preference|architecture|bug|workflow|fact</type>
@@ -3829,7 +3874,11 @@ def consolidate(
             concepts_list = get_xml_children(cleaned, "concepts", "concept")
             files_list = get_xml_children(cleaned, "files", "file")
 
-            now = datetime.datetime.utcnow().isoformat() + "Z"
+            now = (
+                datetime.datetime.now(datetime.timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z")
+            )
 
             # Find existing memory with same title
             existing_match = None
@@ -3934,12 +3983,12 @@ def consolidate(
         )[:20]
 
         SEMANTIC_MERGE_SYSTEM = """You are a memory consolidation engine. Given overlapping episodic memories (session summaries), extract stable factual knowledge.
-        
+
         Output format (XML):
         <facts>
           <fact confidence="0.0-1.0">Concise factual statement</fact>
         </facts>
-        
+
         Rules:
         - Extract only facts that appear in 2+ episodes or are highly confident
         - Confidence reflects how well-supported the fact is across episodes
@@ -3963,7 +4012,11 @@ def consolidate(
             )
 
             existing_semantic = kv.list(KV.semantic)
-            now = datetime.datetime.utcnow().isoformat() + "Z"
+            now = (
+                datetime.datetime.now(datetime.timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z")
+            )
 
             for conf_str, fact_text in fact_matches:
                 fact_text = fact_text.strip()
@@ -4018,7 +4071,7 @@ def consolidate(
 
     if len(patterns) >= 2:
         PROCEDURAL_EXTRACTION_SYSTEM = """You are a procedural memory extractor. Given repeated patterns and workflows observed across sessions, extract reusable procedures.
-        
+
         Output format (XML):
         <procedures>
           <procedure name="short descriptive name" trigger="when to use this procedure">
@@ -4026,7 +4079,7 @@ def consolidate(
             <step>Step 2 description</step>
           </procedure>
         </procedures>
-        
+
         Rules:
         - Only extract procedures observed 2+ times
         - Steps should be concrete and actionable
@@ -4051,7 +4104,11 @@ def consolidate(
             )
 
             existing_procs = kv.list(KV.procedural)
-            now = datetime.datetime.utcnow().isoformat() + "Z"
+            now = (
+                datetime.datetime.now(datetime.timezone.utc)
+                .isoformat()
+                .replace("+00:00", "Z")
+            )
 
             for name, trigger, steps_block in proc_matches:
                 steps = [

src/{import_data.py → agentcache/import_data.py}

@@ -1,11 +1,9 @@
-import os
 import json
-import urllib.parse
+import os
 import sys
+import urllib.parse
 
-# Append local path so we can import StateKV
-sys.path.append(os.path.dirname(os.path.abspath(__file__)))
-from db import StateKV
+from .db import StateKV
 
 
 def import_old_data(old_db_path: str, kv: StateKV) -> bool:

src/{mcp_stdio.py → agentcache/mcp_stdio.py}

@@ -9,9 +9,10 @@ Antigravity sync functions have been moved to examples/antigravity_sync.py (D1.3
 All tool calls are proxied to the HTTP API.
 """
 
-import sys
 import json
 import os
+import sys
+
 import requests
 
 BASE = (

src/{replay_import.py → agentcache/replay_import.py}

@@ -1,9 +1,9 @@
+import datetime
+import hashlib
+import json
 import os
 import re
-import json
-import hashlib
-import datetime
-from typing import List, Dict, Any, Tuple
+from typing import Any, Dict, List, Tuple
 
 # Constants
 MAX_FILES_DEFAULT = 200
@@ -124,7 +124,9 @@ def parse_jsonl_text(text: str, fallback_session_id: str = None) -> Dict[str, An
         if entry.get("cwd") and not cwd:
             cwd = entry["cwd"]
 
-        ts = entry.get("timestamp") or datetime.datetime.utcnow().isoformat() + "Z"
+        ts = entry.get("timestamp") or datetime.datetime.now(
+            datetime.timezone.utc
+        ).isoformat().replace("+00:00", "Z")
         if not first_ts:
             first_ts = ts
         last_ts = ts
@@ -196,7 +198,9 @@ def parse_jsonl_text(text: str, fallback_session_id: str = None) -> Dict[str, An
         if obs["sessionId"] == "imported":
             obs["sessionId"] = effective_session_id
 
-    now_iso = datetime.datetime.utcnow().isoformat() + "Z"
+    now_iso = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
     return {
         "sessionId": effective_session_id,
         "project": derive_project(cwd),
@@ -215,11 +219,13 @@ def derive_crystal_and_lessons(
     compressed: List[Dict[str, Any]],
     first_prompt: str = None,
 ) -> None:
-    from functions import KV
+    from .functions import KV
 
     if not raw_obs:
         return
-    created_at = datetime.datetime.utcnow().isoformat() + "Z"
+    created_at = (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
 
     files = set()
     tools = set()
@@ -362,7 +368,7 @@ def find_jsonl_files(root: str, limit=200) -> Tuple[List[str], bool, int, bool]:
 
 
 def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str, Any]:
-    from functions import KV, build_synthetic_compression, _bm25_index
+    from .functions import KV, _bm25_index, build_synthetic_compression
 
     default_root = os.path.expanduser(os.path.join("~", ".claude", "projects"))
     raw_path = path or default_root
@@ -475,7 +481,7 @@ def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str,
             }
             kv.set(KV.sessions, session["id"], session)
 
-        from functions import vector_index_add_guarded
+        from .functions import vector_index_add_guarded
 
         compressed = []
         for obs in parsed["observations"]:
@@ -506,7 +512,7 @@ def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str,
         )
 
     # Save the updated persistence state
-    import functions
+    from . import functions
 
     if functions._index_persistence:
         try:
@@ -516,7 +522,7 @@ def import_jsonl_data(kv, path: str = None, max_files: int = None) -> Dict[str,
 
     # Audit trail
     try:
-        from functions import log_audit
+        from .functions import log_audit
 
         log_audit(
             kv,
@@ -613,7 +619,11 @@ def estimate_duration_ms(event: Dict[str, Any]) -> int:
 
 def project_timeline(observations: List[Dict[str, Any]]) -> Dict[str, Any]:
     if not observations:
-        now = datetime.datetime.utcnow().isoformat() + "Z"
+        now = (
+            datetime.datetime.now(datetime.timezone.utc)
+            .isoformat()
+            .replace("+00:00", "Z")
+        )
         return {
             "sessionId": "",
             "startedAt": now,

src/{routes → agentcache/routes}/__init__.py

@@ -4,13 +4,13 @@ Flask blueprints for agentmemory-python.
 Import and register all blueprints via register_blueprints(app).
 """
 
-from .observations import observations_bp
-from .memories import memories_bp
-from .search import search_bp
 from .graph import graph_bp
 from .health import health_bp
 from .mcp import mcp_bp
+from .memories import memories_bp
 from .migration import migration_bp
+from .observations import observations_bp
+from .search import search_bp
 
 
 def register_blueprints(app):

src/{routes → agentcache/routes}/graph.py

@@ -9,8 +9,10 @@ Handles:
 """
 
 import os
-from flask import Blueprint, request, jsonify
-import functions
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
 
 graph_bp = Blueprint("graph", __name__)
 
@@ -31,7 +33,7 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 

src/{routes → agentcache/routes}/health.py

@@ -9,9 +9,11 @@ Handles:
 """
 
 import os
-from flask import Blueprint, request, jsonify, Response
-import functions
-from functions import query_audit
+
+from flask import Blueprint, Response, jsonify, request
+
+from .. import functions
+from ..functions import query_audit
 
 health_bp = Blueprint("health", __name__)
 
@@ -32,13 +34,13 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 
 
 def _get_embedding_provider():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.embedding_provider
 

src/{routes → agentcache/routes}/mcp.py

@@ -6,12 +6,14 @@ Handles:
   POST /agentmemory/mcp/tools   — dispatch a tool call
 """
 
-import os
-import json
 import datetime
-from flask import Blueprint, request, jsonify
-import functions
-from functions import KV
+import json
+import os
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
+from ..functions import KV
 
 mcp_bp = Blueprint("mcp", __name__)
 
@@ -32,13 +34,15 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 
 
 def _datetime_now_iso() -> str:
-    return datetime.datetime.utcnow().isoformat() + "Z"
+    return (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
 
 
 def _parse_mcp_list_arg(arg_val):

src/{routes → agentcache/routes}/memories.py

@@ -9,9 +9,11 @@ Handles:
 """
 
 import os
-from flask import Blueprint, request, jsonify
-import functions
-from functions import KV
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
+from ..functions import KV
 
 memories_bp = Blueprint("memories", __name__)
 
@@ -32,7 +34,7 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 

src/{routes → agentcache/routes}/migration.py

@@ -6,8 +6,10 @@ Handles:
 """
 
 import os
-from flask import Blueprint, request, jsonify
-import functions
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
 
 migration_bp = Blueprint("migration", __name__)
 
@@ -28,7 +30,7 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 

src/{routes → agentcache/routes}/observations.py

@@ -8,17 +8,21 @@ Handles:
   GET  /agentmemory/folders
 """
 
-import os
 import datetime
-from flask import Blueprint, request, jsonify
-import functions
-from functions import KV
+import os
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
+from ..functions import KV
 
 observations_bp = Blueprint("observations", __name__)
 
 
 def _datetime_now_iso() -> str:
-    return datetime.datetime.utcnow().isoformat() + "Z"
+    return (
+        datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
+    )
 
 
 def _check_auth():
@@ -39,7 +43,7 @@ def _check_auth():
 
 def _get_kv():
     """Retrieve the shared kv instance from the app module."""
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 

src/{routes → agentcache/routes}/search.py

@@ -7,8 +7,10 @@ Handles:
 """
 
 import os
-from flask import Blueprint, request, jsonify
-import functions
+
+from flask import Blueprint, jsonify, request
+
+from .. import functions
 
 search_bp = Blueprint("search", __name__)
 
@@ -29,7 +31,7 @@ def _check_auth():
 
 
 def _get_kv():
-    import app as app_module
+    from .. import app as app_module
 
     return app_module.kv
 

src/{search.py → agentcache/search.py}

@@ -1,11 +1,11 @@
-import re
-import math
-import json
-import base64
 import array
-import urllib.request
+import base64
+import json
+import math
+import re
 import urllib.parse
-from typing import Dict, Any, List, Optional, Tuple, Set
+import urllib.request
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 # =====================================================================
 # Custom Porter-like Stemmer (Ported from stemmer.ts)

src/{storage → agentcache/storage}/__init__.py

@@ -12,9 +12,9 @@ These are compatibility copies — the originals in functions.py are kept intact
 for backward compatibility.
 """
 
+from .images import delete_image, is_managed_image_path, save_image_to_disk, touch_image
+from .paths import fingerprint_id, generate_id, normalize_folder_path, validate_agent_id
 from .scopes import KV
-from .paths import normalize_folder_path, validate_agent_id, generate_id, fingerprint_id
-from .images import save_image_to_disk, delete_image, touch_image, is_managed_image_path
 
 __all__ = [
     "KV",

src/{storage → agentcache/storage}/images.py

@@ -4,8 +4,8 @@ src/storage/images.py — Image-on-disk storage helpers (A2.3).
 Copied from src/functions.py — do NOT delete the originals (backward compat).
 """
 
-import os
 import hashlib
+import os
 from typing import Optional, Tuple
 
 IMAGES_DIR = os.path.join(os.path.expanduser("~"), ".agentmemory", "images")

src/{storage → agentcache/storage}/paths.py

@@ -4,10 +4,10 @@ src/storage/paths.py — Path normalisation and ID utilities (A2.3).
 Copied from src/functions.py — do NOT delete the originals (backward compat).
 """
 
+import hashlib
 import os
 import time
 import uuid
-import hashlib
 
 # Maximum allowed length for folder paths and agent IDs.
 _MAX_PATH_LEN = 512