Feat/native agent harness

.gitignore

@@ -51,6 +51,18 @@ htmlcov/
 
 # Plans/Documentation (auto-generated or planning)
 plans/
+.codex
+
+# GEPA / experiment artefacts (dashboard branch only)
+INTEGRATIONS_PLAN.md
+docs/MODAL_GEPA.md
+scripts/dspy_gepa_locomo.py
+scripts/eval_gepa_compare.py
+scripts/judge_gepa_compare.py
+scripts/modal_gepa_runner.py
+scripts/modal_vllm_server.py
+data/gepa_*
+data/locomo_*
 
 # OS
 .DS_Store

README.md

@@ -174,6 +174,14 @@ More examples in [`/examples`](examples/):
 - [`quickstart.py`](examples/quickstart.py) — fully local, zero API keys (Ollama)
 - [`openai_agent.py`](examples/openai_agent.py) — OpenAI native harness loop
 - [`vektori_agent_demo.py`](examples/vektori_agent_demo.py) — minimal `VektoriAgent` demo
+- [`gemini_agent_integration_demo.py`](examples/gemini_agent_integration_demo.py) — Gemini extraction + agent chat showcase
+- [`gemini_agent_ui.py`](examples/gemini_agent_ui.py) — single-file local web UI that shows chat + live memory trace
+- [`integrating_hermes_openclaw.py`](examples/integrating_hermes_openclaw.py) — Hermes/OpenClaw adapter wiring example
+- [`real_world_support_case.py`](examples/real_world_support_case.py) — realistic support handoff / follow-up smoke test
+
+For a live end-to-end harness check, run [`scripts/test_agent_e2e.py`](scripts/test_agent_e2e.py). It exercises retrieval, profile learning, tool calling, and window persistence against real providers.
+
+Hermes/OpenClaw support in this repo is currently an integration starter path (adapter/plugin wiring), not a widely benchmarked default harness.
 
 ---
 

demo.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# vektori demo script — for screen recording
+# run: bash demo.sh
+# tip: use a terminal with big font, dark theme, ~100 cols wide
+
+set -euo pipefail
+
+BOLD="\033[1m"
+DIM="\033[2m"
+GREEN="\033[32m"
+CYAN="\033[36m"
+YELLOW="\033[33m"
+RED="\033[31m"
+RESET="\033[0m"
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+hr() { printf "${DIM}%0.s─${RESET}" $(seq 1 60); echo; }
+
+type_cmd() {
+    # prints a "typed" prompt then runs the command
+    local cmd="$1"
+    printf "\n${GREEN}❯${RESET} "
+    for ((i=0; i<${#cmd}; i++)); do
+        printf "%s" "${cmd:$i:1}"
+        sleep 0.03
+    done
+    echo
+    sleep 0.6
+    eval "$cmd"
+}
+
+pause() { sleep "${1:-2}"; }
+
+section() {
+    echo
+    hr
+    printf "${BOLD}${CYAN}  $1${RESET}\n"
+    hr
+    pause 1
+}
+
+# ── env ──────────────────────────────────────────────────────────────────────
+
+export VEKTORI_USER_ID="${VEKTORI_USER_ID:-dev}"
+export VEKTORI_EXTRACTION_MODEL="${VEKTORI_EXTRACTION_MODEL:-litellm:groq/llama-3.3-70b-versatile}"
+export VEKTORI_EMBEDDING_MODEL="${VEKTORI_EMBEDDING_MODEL:-sentence-transformers:all-MiniLM-L6-v2}"
+
+# ── SCENE 1: the hook ─────────────────────────────────────────────────────────
+
+clear
+pause 1
+
+echo
+printf "${BOLD}  your AI assistant forgets everything after every session.${RESET}\n"
+pause 2
+printf "${DIM}  every project. every decision. every bug. gone.${RESET}\n"
+pause 2
+printf "${DIM}  mem0 charges you \$50/month to fix this.${RESET}\n"
+pause 2
+printf "${YELLOW}${BOLD}  we just read ~/.claude${RESET}\n"
+pause 3
+
+# ── SCENE 2: detect ──────────────────────────────────────────────────────────
+
+section "STEP 1 — vektori detects your sessions"
+
+type_cmd "vektori inject -u dev --list"
+pause 3
+
+# ── SCENE 3: inject ──────────────────────────────────────────────────────────
+
+section "STEP 2 — inject everything. one command."
+
+type_cmd "vektori inject -u dev --since 30 --yes"
+pause 2
+
+type_cmd "vektori stats -u dev"
+pause 3
+
+# ── SCENE 4: recall across sessions ──────────────────────────────────────────
+
+section "STEP 3 — now ask anything. across every session."
+
+echo
+printf "${DIM}  (claude code and codex sessions. all projects. past 30 days.)${RESET}\n"
+pause 2
+
+type_cmd "vektori recall \"what was the engram project about?\" -u dev"
+pause 3
+
+type_cmd "vektori recall \"what did we build at the hackathon?\" -u dev"
+pause 3
+
+type_cmd "vektori recall \"what storage backends did we add to vektori?\" -u dev"
+pause 3
+
+# ── SCENE 5: L2 — the full story ─────────────────────────────────────────────
+
+section "STEP 4 — L2: reconstruct the full conversation"
+
+echo
+printf "${DIM}  L0 = just facts.  L1 = facts + source sentences.  L2 = full story.${RESET}\n"
+pause 2
+
+type_cmd "vektori search \"vektori storage decisions\" -u dev --depth l2"
+pause 4
+
+# ── SCENE 6: cross-project ────────────────────────────────────────────────────
+
+section "STEP 5 — cross-project memory"
+
+type_cmd "vektori search \"what projects have we shipped\" -u dev --depth l1 --top-k 6"
+pause 3
+
+type_cmd "vektori search \"what bugs did codex fix on vektori\" -u dev --expand"
+pause 3
+
+# ── SCENE 7: the closer ───────────────────────────────────────────────────────
+
+echo
+hr
+echo
+printf "${BOLD}  every claude code session. every codex session.${RESET}\n"
+pause 1
+printf "${BOLD}  across every project. fully searchable.${RESET}\n"
+pause 1
+printf "${BOLD}  L0 / L1 / L2 depth. semantic search. zero cloud.${RESET}\n"
+pause 2
+echo
+printf "${GREEN}${BOLD}  pip install vektori${RESET}\n"
+echo
+hr
+echo

docs/AGENT_HARNESS_CHECKLIST.md

@@ -0,0 +1,33 @@
+# Agent Harness Checklist
+
+This tracks the current implementation status against `docs/AGENT_HARNESS_SPEC.md`.
+
+## Implemented
+
+- `VektoriAgent`, `AgentConfig`, and `AgentTurnResult`
+- Separate `ChatModelProvider` / `ChatCompletionResult`
+- `AgentContextLoader` for `agents.md` and `vektori.yaml`
+- `MessageWindow` with local compaction
+- `ProfilePatch` lane with in-memory and SQLite-backed stores
+- Explicit profile learning (name, verbosity, units patterns)
+- Deterministic prompt assembly with token budgeting and trimming
+- Retrieval decision diagnostics on each turn
+- Native CLI chat entrypoint via `vektori agent chat`
+- **Phase 4 — Tool calling**: `vektori/tools/memory.py` with `search_memory`, `get_profile`, `update_profile` schemas + multi-round-trip tool loop in `VektoriAgent`
+- **Phase 5 — Window persistence**: `SQLiteWindowStore` with `save_window()` / `resume_window()` on agent; sessions resumable across process restarts
+- E2E integration test script: `scripts/test_agent_e2e.py`
+
+## Partial
+
+- Profile learning rules are explicit but still heuristic-driven (regex patterns only)
+- Theory-of-Mind isolation exists in profile storage, not yet a broader runtime concept
+- Context parsing is forgiving; not fully normalized for complex YAML
+- Cold-path pipeline is `asyncio.create_task`, not a dedicated worker queue
+
+## Missing / Next
+
+- Anthropic `AnthropicChatModel` and Ollama registration in `CHAT_REGISTRY`
+- Richer prompt budgeting with exact tokenization (tiktoken / provider tokenizers)
+- Tool calling for Anthropic API (uses different tool_use schema)
+- Compaction summaries optionally persisted as tagged episodic memory (Phase 5b)
+- Cross-session planning / multi-agent shared windows