agent-mockingbird 0.0.1

package/bunfig.toml

@@ -0,0 +1,2 @@
+[install]
+linker = "hoisted"

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

package/config.json

@@ -0,0 +1,130 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "command": {
+    "tokenscope": {
+      "template": "Call the tokenscope tool directly without delegating to other agents.\nThen cat the token-usage-output.txt. DONT DO ANYTHING ELSE WITH THE OUTPUT.\n• Call the two tools\n• Not add any additional text or formatting after that",
+      "description": "Analyze token usage across the current session with detailed breakdowns by category"
+    }
+  },
+  "skills": {
+    "paths": [
+      "/var/home/matt/Documents/random-vibecoded-stuff/agent-mockingbird/.agents/skills"
+    ]
+  },
+  "plugin": [
+    "file:///var/home/matt/.config/opencode/plugin/tokenscope.ts"
+  ],
+  "model": "anthropic/claude-opus-4-5",
+  "small_model": "chutes/openai/gpt-oss-120b-TEE",
+  "username": "matt",
+  "mode": {},
+  "agent": {
+    "explore": {
+      "model": "chutes/MiniMaxAI/MiniMax-M2.5-TEE",
+      "options": {},
+      "permission": {}
+    },
+    "king-mode": {
+      "prompt": "# SYSTEM ROLE & BEHAVIORAL PROTOCOLS\n\n**ROLE:** Senior Frontend Architect & Avant-Garde UI Designer.\n**EXPERIENCE:** 15+ years. Master of visual hierarchy, whitespace, and UX engineering.\n\n## 1. OPERATIONAL DIRECTIVES (DEFAULT MODE)\n\n- **Follow Instructions:** Execute the request immediately. Do not deviate.\n- **Zero Fluff:** No philosophical lectures or unsolicited advice in standard mode.\n- **Stay Focused:** Concise answers only. No wandering.\n- **Output First:** Prioritize code and visual solutions.\n\n## 2. THE \"ULTRATHINK\" PROTOCOL (TRIGGER COMMAND)\n\n**TRIGGER:** When the user prompts **\"ULTRATHINK\"**:\n\n- **Override Brevity:** Immediately suspend the \"Zero Fluff\" rule.\n- **Maximum Depth:** You must engage in exhaustive, deep-level reasoning.\n- **Multi-Dimensional Analysis:** Analyze the request through every lens:\n  - _Psychological:_ User sentiment and cognitive load.\n  - _Technical:_ Rendering performance, repaint/reflow costs, and state complexity.\n  - _Accessibility:_ WCAG AAA strictness.\n  - _Scalability:_ Long-term maintenance and modularity.\n- **Prohibition:** **NEVER** use surface-level logic. If the reasoning feels easy, dig deeper until the logic is irrefutable.\n\n## 3. DESIGN PHILOSOPHY: \"INTENTIONAL MINIMALISM\"\n\n- **Anti-Generic:** Reject standard \"bootstrapped\" layouts. If it looks like a template, it is wrong.\n- **Uniqueness:** Strive for bespoke layouts, asymmetry, and distinctive typography.\n- **The \"Why\" Factor:** Before placing any element, strictly calculate its purpose. If it has no purpose, delete it.\n- **Minimalism:** Reduction is the ultimate sophistication.\n\n## 4. FRONTEND CODING STANDARDS\n\n- **Library Discipline (CRITICAL):** If a UI library (e.g., Shadcn UI, Radix, MUI) is detected or active in the project, **YOU MUST USE IT**.\n  - **Do not** build custom components (like modals, dropdowns, or buttons) from scratch if the library provides them.\n  - **Do not** pollute the codebase with redundant CSS.\n  - _Exception:_ You may wrap or style library components to achieve the \"Avant-Garde\" look, but the underlying primitive must come from the library to ensure stability and accessibility.\n- **Stack:** Modern (React/Vue/Svelte), Tailwind/Custom CSS, semantic HTML5.\n- **Visuals:** Focus on micro-interactions, perfect spacing, and \"invisible\" UX.\n\n## 5. RESPONSE FORMAT\n\n**IF NORMAL:**\n\n1.  **Rationale:** (1 sentence on why the elements were placed there).\n2.  **The Code.**\n\n**IF \"ULTRATHINK\" IS ACTIVE:**\n\n1.  **Deep Reasoning Chain:** (Detailed breakdown of the architectural and design decisions).\n2.  **Edge Case Analysis:** (What could go wrong and how we prevented it).\n3.  **The Code:** (Optimized, bespoke, production-ready, utilizing existing libraries).",
+      "description": "Reviews code for quality and best practices",
+      "mode": "all",
+      "options": {},
+      "permission": {},
+      "name": "king-mode"
+    }
+  },
+  "mcp": {},
+  "permission": {
+    "bash": {
+      "git push": "deny",
+      "git pull": "deny",
+      "git commit": "deny",
+      "btca": "allow",
+      "sed": "allow",
+      "git status": "allow",
+      "git diff": "allow",
+      "p compile": "allow",
+      "pnpm compile": "allow",
+      "p lint": "allow",
+      "pnpm lint": "allow",
+      "pnpm lint:check": "allow",
+      "pnpm add": "ask",
+      "ls": "allow",
+      "grep": "allow",
+      "pwd": "allow",
+      "rm": "ask",
+      "gh pr diff": "allow",
+      "rmdir": "ask",
+      "unlink": "deny",
+      "shred": "deny",
+      "git reset": "deny",
+      "git clean": "deny",
+      "git branch -D": "deny",
+      "git branch -d": "deny",
+      "git rebase": "deny",
+      "git filter-branch": "deny",
+      "git checkout -b": "deny",
+      "git checkout": "deny",
+      "git remote": "deny",
+      "git init": "deny",
+      "git config": "deny",
+      "sudo": "deny",
+      "su": "deny",
+      "pkexec": "deny",
+      "ssh": "deny",
+      "scp": "deny",
+      "sftp": "deny",
+      "rsync": "deny",
+      "curl": "deny",
+      "wget": "deny",
+      "nc": "deny",
+      "netcat": "deny",
+      "telnet": "deny",
+      "ftp": "deny",
+      "chmod": "deny",
+      "chown": "deny",
+      "chgrp": "deny",
+      "mount": "deny",
+      "umount": "deny",
+      "fdisk": "deny",
+      "gdisk": "deny",
+      "parted": "deny",
+      "mkfs": "deny",
+      "fsck": "deny",
+      "dd": "deny",
+      "npm install -g": "deny",
+      "npm g": "deny",
+      "yarn global": "deny",
+      "brew": "deny",
+      "apt": "deny",
+      "apt-get": "deny",
+      "yum": "deny",
+      "dnf": "deny",
+      "pip": "deny",
+      "eval": "deny",
+      "exec": "deny",
+      "bash": "deny",
+      "sh": "deny",
+      "zsh": "deny",
+      "crontab": "deny",
+      "systemctl": "deny",
+      "service": "deny",
+      "shutdown": "deny",
+      "reboot": "deny",
+      "halt": "deny",
+      "poweroff": "deny",
+      "adb install": "deny",
+      "adb push": "deny",
+      "adb shell": "deny",
+      "xcodebuild": "deny",
+      "p start": "deny",
+      "pnpm start": "deny"
+    },
+    "skill": {
+      "*": "deny",
+      "config-auditor": "allow",
+      "config-editor": "allow",
+      "runtime-diagnose": "allow"
+    }
+  }
+}

package/deploy/RELEASE_INSTALL.md

@@ -0,0 +1,112 @@
+# Release + Install
+
+This project is published to npm and source-hosted on GitHub.
+
+## User onboarding flow (npm + systemd user services)
+
+Recommended first-run flow on Linux:
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/waffleophagus/agent-mockingbird/main/scripts/onboard/bootstrap.sh" | bash
+```
+
+This installs:
+
+- `agent-mockingbird` from npmjs
+- `opencode-ai` from npmjs
+- user services (`opencode.service`, `agent-mockingbird.service`) in `~/.config/systemd/user`
+- automatic service start and health verification
+- interactive onboarding on TTY installs (`provider auth`, default model, memory/Ollama, optional OpenClaw import)
+
+Install root defaults to `~/.agent-mockingbird`.
+
+After install, operational commands are available through `agent-mockingbird`:
+
+```bash
+agent-mockingbird status
+agent-mockingbird restart
+agent-mockingbird update
+```
+
+Fallback bootstrap wrapper:
+
+```bash
+curl -fsSL "https://raw.githubusercontent.com/waffleophagus/agent-mockingbird/main/scripts/onboard/bootstrap.sh" | bash
+```
+
+Feature branch preview install:
+
+```bash
+BRANCH="<branch-name>"
+VERSION="<published-preview-version>"
+AGENT_MOCKINGBIRD_TAG="${VERSION}" \
+  curl -fsSL "https://raw.githubusercontent.com/waffleophagus/agent-mockingbird/${BRANCH}/scripts/onboard/bootstrap.sh" | bash
+```
+
+## Maintainer flow (build + publish)
+
+1. Add `NPM_TOKEN` as a GitHub Actions repository secret with publish access for the `@waffleophagus` scope.
+2. Push a tag like `v0.1.0` from `main` to publish the release pair to npm tag `latest`.
+3. Push a non-`main` branch as `waffleophagus` to publish a preview pair to npm tag `next`.
+4. Plain pushes to `main` run checks only; they do not publish.
+
+For branch previews, pin `AGENT_MOCKINGBIRD_TAG` to the exact published `next` version so the bootstrap script and package version match.
+
+Repository build policy:
+
+- `dist/app` is treated as a committed artifact generated locally before commit.
+- The repo `pre-commit` hook runs lint, typecheck, `build`, and `build:bin`, then stages `dist/app`.
+- CI no longer rebuilds the OpenCode web bundle from vendored dependencies; it verifies the committed `dist/app` bundle and rebuilds only the standalone runtime binary.
+
+## Manual host install flow
+
+Clone a tagged revision on your target Linux host, then run the bundled install script:
+
+```bash
+git clone https://github.com/waffleophagus/agent-mockingbird.git
+cd agent-mockingbird
+git checkout v0.1.0
+sudo bash scripts/install-systemd.sh
+```
+
+Optional install overrides:
+
+```bash
+sudo AGENT_MOCKINGBIRD_USER=agent-mockingbird \
+  AGENT_MOCKINGBIRD_GROUP=agent-mockingbird \
+  AGENT_MOCKINGBIRD_APP_DIR=/srv/agent-mockingbird/app \
+  AGENT_MOCKINGBIRD_DATA_DIR=/var/lib/agent-mockingbird \
+  bash scripts/install-systemd.sh
+```
+
+Prerequisites on host:
+
+- `bun` in `PATH`
+- `opencode` in `PATH`
+- `systemd`
+
+After install, verify:
+
+```bash
+systemctl status opencode.service --no-pager
+systemctl status agent-mockingbird.service --no-pager
+curl -sS http://127.0.0.1:3001/api/health
+```
+
+For tailnet access, expose the local service with:
+
+```bash
+tailscale serve --bg 3001
+```
+
+## Install via Git URL (Bun global)
+
+No package registry is required. Install directly from the git tag:
+
+```bash
+OWNER="<github-owner>"
+REPO="<repo-name>"
+VERSION="v0.1.0"
+bun add -g "github:${OWNER}/${REPO}#${VERSION}"
+agent-mockingbird
+```

package/deploy/docker-compose.yml

@@ -0,0 +1,42 @@
+version: "3.9"
+services:
+  opencode:
+    image: ghcr.io/sst/opencode:latest
+    command: ["serve", "--hostname", "0.0.0.0", "--port", "4096", "--print-logs", "--log-level", "INFO"]
+    working_dir: /workspace
+    volumes:
+      - ../:/workspace
+      - agent_mockingbird_data:/var/lib/agent-mockingbird
+    environment:
+      AGENT_MOCKINGBIRD_MEMORY_API_BASE_URL: http://agent-mockingbird:3001
+      OPENCODE_CONFIG_DIR: /var/lib/agent-mockingbird/opencode-config/docker
+      OPENCODE_DISABLE_PROJECT_CONFIG: "1"
+    ports:
+      - "4096:4096"
+
+  agent-mockingbird:
+    image: oven/bun:1.3
+    working_dir: /workspace
+    command:
+      [
+        "/bin/bash",
+        "-lc",
+        "AGENT_MOCKINGBIRD_OPENCODE_BASE_URL=http://opencode:4096 OPENCODE_CONFIG_DIR=/var/lib/agent-mockingbird/opencode-config/docker OPENCODE_DISABLE_PROJECT_CONFIG=1 bun run config:migrate-opencode-env >/dev/null || true; exec bun src/index.ts",
+      ]
+    depends_on:
+      - opencode
+    volumes:
+      - ../:/workspace
+      - agent_mockingbird_data:/var/lib/agent-mockingbird
+    environment:
+      NODE_ENV: production
+      PORT: "3001"
+      AGENT_MOCKINGBIRD_CONFIG_PATH: /var/lib/agent-mockingbird/agent-mockingbird.config.json
+      AGENT_MOCKINGBIRD_DB_PATH: /var/lib/agent-mockingbird/agent-mockingbird.db
+      OPENCODE_CONFIG_DIR: /var/lib/agent-mockingbird/opencode-config/docker
+      OPENCODE_DISABLE_PROJECT_CONFIG: "1"
+    ports:
+      - "3001:3001"
+
+volumes:
+  agent_mockingbird_data:

package/deploy/systemd/README.md

@@ -0,0 +1,46 @@
+# Systemd Deployment (Sidecar Model)
+
+This setup runs **two services on one VM**:
+
+- `opencode.service` (local sidecar on `127.0.0.1:4096`)
+- `agent-mockingbird.service` (dashboard/API on `127.0.0.1:3001`)
+
+Both are pinned to one project workspace (`/srv/agent-mockingbird/app`).
+
+## 1. Install units
+
+```bash
+sudo install -D -m 0644 deploy/systemd/opencode.service /etc/systemd/system/opencode.service
+sudo install -D -m 0644 deploy/systemd/agent-mockingbird.service /etc/systemd/system/agent-mockingbird.service
+sudo systemctl daemon-reload
+```
+
+## 2. Enable + start
+
+```bash
+sudo systemctl enable --now opencode.service agent-mockingbird.service
+```
+
+## 3. Verify
+
+```bash
+systemctl status opencode.service --no-pager
+systemctl status agent-mockingbird.service --no-pager
+curl -sS http://127.0.0.1:3001/api/health
+curl -sS http://127.0.0.1:3001/api/runtime/info
+```
+
+## 4. Logs
+
+```bash
+journalctl -u opencode.service -f
+journalctl -u agent-mockingbird.service -f
+```
+
+## Notes
+
+- OpenCode runtime settings (`baseUrl`, `directory`, model/provider/timeouts) now come from agent-mockingbird config JSON (`runtime.opencode.*`), not runtime env vars.
+- Set `AGENT_MOCKINGBIRD_MEMORY_WORKSPACE_DIR` in `agent-mockingbird.service` to the same project path used by `opencode.service` `WorkingDirectory`.
+- If migrating older env-based settings, run `bun run config:migrate-opencode-env` once before service start.
+- Agent edits from Agent Mockingbird persist to the managed OpenCode config dir pointed to by `OPENCODE_CONFIG_DIR`, not to project-local `.opencode`.
+- If OpenCode TUI/web appears different, launch/attach it with the same workspace directory.

package/deploy/systemd/agent-mockingbird.service

@@ -0,0 +1,28 @@
+[Unit]
+Description=Agent Mockingbird API and Dashboard
+After=network.target opencode.service
+Wants=network.target opencode.service
+
+[Service]
+Type=simple
+User=agent-mockingbird
+Group=agent-mockingbird
+WorkingDirectory=/srv/agent-mockingbird/app
+Environment=NODE_ENV=production
+Environment=PORT=3001
+Environment=AGENT_MOCKINGBIRD_CONFIG_PATH=/var/lib/agent-mockingbird/agent-mockingbird.config.json
+Environment=AGENT_MOCKINGBIRD_DB_PATH=/var/lib/agent-mockingbird/agent-mockingbird.db
+Environment=AGENT_MOCKINGBIRD_MEMORY_WORKSPACE_DIR=/srv/agent-mockingbird/app
+Environment=OPENCODE_CONFIG_DIR=__AGENT_MOCKINGBIRD_OPENCODE_CONFIG_DIR__
+Environment=OPENCODE_DISABLE_PROJECT_CONFIG=1
+ExecStart=/usr/bin/env bun apps/server/src/index.ts
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=/srv/agent-mockingbird/app /var/lib/agent-mockingbird
+
+[Install]
+WantedBy=multi-user.target

package/deploy/systemd/opencode.service

@@ -0,0 +1,25 @@
+[Unit]
+Description=OpenCode Sidecar for Agent Mockingbird
+After=network.target
+Wants=network.target
+
+[Service]
+Type=simple
+User=agent-mockingbird
+Group=agent-mockingbird
+WorkingDirectory=/srv/agent-mockingbird/app
+Environment=AGENT_MOCKINGBIRD_PORT=3001
+Environment=AGENT_MOCKINGBIRD_MEMORY_API_BASE_URL=http://127.0.0.1:3001
+Environment=OPENCODE_CONFIG_DIR=__AGENT_MOCKINGBIRD_OPENCODE_CONFIG_DIR__
+Environment=OPENCODE_DISABLE_PROJECT_CONFIG=1
+ExecStart=/usr/bin/env opencode serve --hostname 127.0.0.1 --port 4096 --print-logs --log-level INFO
+Restart=always
+RestartSec=2
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=read-only
+ReadWritePaths=/srv/agent-mockingbird/app /var/lib/agent-mockingbird
+
+[Install]
+WantedBy=multi-user.target

package/docs/legacy-config-ui-reference.md

@@ -0,0 +1,51 @@
+# Legacy Config UI Reference (Add-Back TODO)
+
+Status: keep this while we clone/adapt Opencode UI; use it to reintroduce non-chat functionality.
+
+## Goal
+Re-add legacy Agent Mockingbird functionality on top of the Opencode-like React UI after the base shell is stable.
+
+## Add Back: Skills
+- Skills list (view/search/sort as needed).
+- Create/edit/delete skill flows.
+- Prompt/content editor with validation.
+- Enable/disable state and persistence.
+
+## Add Back: MCP
+- MCP server list + status indicators.
+- Add/edit/remove MCP server configs.
+- Env/header/transport configuration fields.
+- Connect/disconnect/test actions.
+
+## Add Back: Agents
+- Agent list and selection UX.
+- Create/edit/duplicate/delete flows.
+- Model, system prompt, and tool-permission settings.
+- Persistence + refresh behavior.
+
+## Add Back: Other Settings
+- Runtime/provider/config toggles from legacy UI.
+- Non-chat operational settings.
+- Save/validation/error feedback patterns.
+
+## Add Back: Cron
+- Cron job list and schedule editor.
+- Enable/disable/delete controls.
+- Run-now action + last run/error status.
+
+## Shared UX/Behavior Requirements
+- Unsaved changes detection + confirm dialog.
+- Consistent toasts for success/error.
+- Loading/empty/error states on each screen.
+- Safe data updates (optimistic only where low risk).
+
+## Suggested Reintroduction Order
+1. Skills
+2. Agents
+3. MCP
+4. Other Settings
+5. Cron
+
+## Notes
+- Non-production app: breaking changes are acceptable.
+- Favor fresh implementations against current APIs/data shapes.

package/docs/memory-e2e-trace-2026-03-04.md

@@ -0,0 +1,63 @@
+# Memory E2E Trace (QMD + sqlite-vec)
+
+Date: 2026-03-04
+Repo: `/var/home/matt/Documents/random-vibecoded-stuff/agent-mockingbird`
+
+## Goal
+Verify end-to-end memory ingest and retrieval behavior with the family prompt scenario, and inspect debug traces from the current `qmd_hybrid` pipeline.
+
+## Commands Run
+```bash
+bun run src/backend/memory/cli.ts status
+bun run src/backend/memory/cli.ts remember "My wife's name is Tiffany and my daughter is Lucy Lee."
+bun run src/backend/memory/cli.ts sync
+bun run src/backend/memory/cli.ts status
+bun run src/backend/memory/cli.ts search --debug "who is my daughter?"
+bun run src/backend/memory/cli.ts search --debug "who is my wife?"
+bun run src/backend/memory/cli.ts search --debug "family members relatives spouse children parents siblings"
+bun run src/backend/memory/cli.ts search --debug "family"
+```
+
+Raw capture file: `/tmp/agent-mockingbird-memory-trace-output.txt`
+
+## Key Results
+
+### 1) Vector backend is active
+After sync, memory status showed:
+- `vectorBackendConfigured: "sqlite_vec"`
+- `vectorBackendActive: "sqlite_vec"`
+- `vectorAvailable: true`
+- `vectorDims: 2560`
+- `vectorIndexedChunks: 2`
+
+### 2) Specific relation queries work
+Query: `who is my daughter?`
+- Returned memory chunk from `memory/2026-03-04.md#L1`
+- Snippet includes: `... my daughter is Lucy Lee.`
+- Score: `0.9291`
+
+Query: `who is my wife?`
+- Returned same chunk
+- Snippet includes: `My wife's name is Tiffany ...`
+- Score: `0.9331`
+
+### 3) Broad family queries still fail
+Query: `family members relatives spouse children parents siblings`
+- `debug.rankedLists` showed multiple vector lists with `count: 2`
+- Final `results` was `[]`
+
+Query: `family`
+- `debug.rankedLists` also showed vector list counts
+- Final `results` was `[]`
+
+## Interpretation
+The vector stage appears to retrieve candidates, but they are filtered out later. Likely reasons in current pipeline:
+- Lexical gating in final filtering rejects candidates that do not share query tokens (`family`, etc.) even when semantic vector match exists.
+- `minScore` threshold can further remove surviving candidates.
+
+Relevant code paths:
+- Vector retrieval and fallback: `src/backend/memory/service.ts` (`searchVectorCandidates`)
+- Final filtering: `src/backend/memory/service.ts` (`applyFinalFiltering` + lexical signal check)
+
+## Conclusion
+The sqlite-vec backend is working and integrated correctly with existing Ollama embeddings. The remaining miss is primarily in post-retrieval filtering behavior for broad category queries like `family`, not vector indexing itself.

package/docs/memory-ops.md

@@ -0,0 +1,96 @@
+# Memory Ops Runbook
+
+This runbook is for Agent Mockingbird operators maintaining OpenCode-backed memory.
+
+## Source of Truth
+
+- Durable files in workspace:
+  - `MEMORY.md`
+  - `memory/*.md`
+- Indexed state in Agent Mockingbird SQLite tables:
+  - `memory_files`
+  - `memory_chunks`
+  - `memory_chunks_fts`
+  - `memory_records`
+  - `memory_embedding_cache`
+  - `memory_write_events`
+
+## Routine Operations
+
+- Check status:
+
+```bash
+bun run memory:status
+```
+
+- Incremental sync (normal path):
+
+```bash
+bun run memory:sync
+```
+
+- Forced rebuild (index corruption/config drift):
+
+```bash
+bun run memory:reindex
+```
+
+- Write-path validation and history:
+
+```bash
+bun run memory:activity 20
+bun run memory:lint
+bun run memory:migrate-format
+```
+
+## API Equivalents
+
+- `GET /api/memory/status`
+- `GET /api/memory/activity?limit=20`
+- `POST /api/memory/sync`
+- `POST /api/memory/reindex`
+- `POST /api/memory/retrieve`
+- `POST /api/memory/read`
+- `POST /api/memory/remember`
+- `POST /api/memory/remember/validate`
+
+## When to Use Sync vs Reindex
+
+- Use `sync` for normal operation and regular maintenance.
+- Use `reindex` when:
+  - embedding provider/model changed,
+  - file/index mismatch is suspected,
+  - retrieval quality regressed after significant workspace updates.
+
+## Recommended Baseline Knobs
+
+- `runtime.memory.toolMode`: `tool_only`
+- `runtime.memory.maxResults`: `4`
+- `runtime.memory.minScore`: `0.35`
+- `runtime.memory.retrieval.engine`: `qmd_hybrid`
+- `runtime.memory.retrieval.strongSignalMinScore`: `0.85`
+- `runtime.memory.retrieval.strongSignalMinGap`: `0.15`
+- `runtime.memory.retrieval.conceptExpansionEnabled`: `true`
+- `runtime.memory.retrieval.conceptExpansionMaxPacks`: `3`
+- `runtime.memory.retrieval.conceptExpansionMaxTerms`: `10`
+- `runtime.memory.retrieval.semanticRescueEnabled`: `true`
+- `runtime.memory.retrieval.semanticRescueMinVectorScore`: `0.75`
+- `runtime.memory.retrieval.semanticRescueMaxResults`: `2`
+
+## Failure Handling
+
+- `Memory is disabled.`
+  - Check `runtime.memory.enabled` in config.
+- Ollama/embed failures
+  - Verify `runtime.memory.ollamaBaseUrl`, provider/model availability, and network reachability.
+- Empty retrieval despite expected content
+  - Run `reindex`, then test with `memory:search`.
+  - Use `memory:search --debug "<query>"` to inspect retrieval legs and expansion behavior.
+- Duplicate write rejections
+  - Expected behavior; check `memory_write_events`/`memory:activity` and write with supersession intent when replacing data.
+
+## Operational Notes
+
+- Keep OpenCode workspace and memory workspace aligned.
+- Prefer deterministic maintenance via cron `memory.maintenance` if periodic sync is needed.
+- Treat memory markdown as canonical; do not manually edit SQLite memory tables.

package/docs/memory-runtime-contract.md

@@ -0,0 +1,42 @@
+# Memory Runtime Contract
+
+This contract defines how OpenCode runtime memory is expected to behave in Agent Mockingbird.
+
+## Contract
+
+- Memory files in workspace (`MEMORY.md`, `memory/*.md`) are canonical.
+- Runtime retrieval uses hybrid ranking over text + vector signals.
+- `memory_get` only reads allowed memory paths.
+- `memory_remember` validates input and logs accepted/rejected events.
+
+## Tool Modes
+
+- Default mode is `tool_only`.
+- `hybrid`: prompt memory injection and memory tool policy are active.
+- `inject_only`: prompt memory injection only.
+- `tool_only`: no prompt injection; retrieval/writes via tools only.
+
+## Retrieval Rules
+
+- Query flow:
+  1. refresh index (cooldown-aware),
+  2. run BM25 probe and skip expansion when strong signal thresholds are met,
+  3. optionally expand typed queries (`lex|vec|hyde`) and route `lex->FTS`, `vec/hyde->vector`,
+  4. fuse result lists with reciprocal rank fusion (RRF), then apply recency and record-state weighting,
+  5. blend rank/rerank signals, apply relevance filtering, and return citations (`path#line`) with clipped snippets.
+- Prompt injection dedupe tracks already-injected memory keys per session generation and resets on session compaction.
+- Retrieval defaults are controlled by `runtime.memory.retrieval.*` and can fall back to `legacy` mode.
+
+## Write Rules
+
+- Empty content is rejected.
+- Duplicate active records are rejected.
+- Accepted writes append compact structured markdown blocks under `memory/YYYY-MM-DD.md` and are indexed.
+- Every write attempt is logged in memory activity.
+
+## Interfaces
+
+- Memory API routes under `/api/memory/*`.
+- OpenCode plugin-provided memory tools under the managed OpenCode config dir `plugins/agent-mockingbird.ts`.
+- Operator CLI via `bun run memory:*` scripts.
+- Retrieval debug can be requested via `POST /api/memory/retrieve` with `{ "debug": true }`.