trailmem 0.1.0__tar.gz

trailmem-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Python packaging and local environments
+.venv/
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+
+# Local Trailmem runtime data
+.trailmem/
+
+# Regeneratable Graphify output
+graphify-out/
+
+# Editor and OS files
+.vscode/
+.idea/
+.DS_Store
+
+# OpenKnowledge local runtime data
+.ok/*.db
+.ok/local/
+
+# Claude Code local settings
+.claude/settings.local.json
+.claude/

trailmem-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amit Kushwaha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trailmem-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: trailmem
+Version: 0.1.0
+Summary: Local-first, graph-linked persistent memory for AI coding agents (MCP server + CLI)
+Project-URL: Homepage, https://github.com/amit/trailmem
+Author-email: Amit Kushwaha <amitkushwaha2805@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,knowledge-graph,mcp,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp
+Requires-Dist: numpy
+Requires-Dist: onnxruntime
+Requires-Dist: orjson
+Requires-Dist: sqlite-vec<0.2.0
+Requires-Dist: tokenizers
+Description-Content-Type: text/markdown
+
+# trailmem
+
+**Persistent, local-first graph memory for AI coding agents.**
+
+Trailmem gives agents durable cross-session memory without provider lock-in: a local SQLite knowledge graph, typed relationships, explicit knowledge evolution, and token-disciplined briefings. It is designed for multiple local agents—Claude, Kiro, Codex, OpenCode, Kilo, and Gemini—to share useful project knowledge without silently creating junk memories.
+
+## Quick start
+
+Same commands on Windows, macOS, and Linux (pure Python; wheels ship for all three). On some systems use `pip3` or `python -m pip` instead of `pip`.
+
+```bash
+pip install trailmem
+trailmem setup          # creates ~/.trailmem/, inits DB, downloads the default embedding model
+trailmem doctor         # health check
+
+# Register the MCP server with your agent host(s):
+trailmem integrate      # detects installed agent hosts, asks before writing any config
+```
+
+`trailmem integrate` auto-detects nine hosts: **Claude Code, Codex, Kiro, Kilo, OpenCode, Antigravity, Zed, Cursor, Windsurf**. It shows what it found, asks once (y/N), backs up every config it touches (`.bak-trailmem`), skips hosts that are already registered, and never rewrites a config it can't parse losslessly (JSONC with comments gets the manual entry printed instead).
+
+Prefer manual registration? Each host has its own mechanism:
+
+| Host | Manual registration |
+|------|--------------------|
+| Claude Code | `claude mcp add trailmem -- trailmem-mcp` |
+| Codex | add an `[mcp_servers.trailmem]` table to `~/.codex/config.toml` |
+| Kiro | add `trailmem` under `mcpServers` in `~/.kiro/settings/mcp.json` |
+| Kilo | add `trailmem` under `mcpServers` in `~/.config/kilo/kilo.jsonc` |
+| OpenCode | add `trailmem` under `mcp` in `~/.config/opencode/opencode.json` |
+| Antigravity | add `trailmem` under `mcpServers` in `~/.gemini/config/mcp_config.json` |
+| Zed | add `trailmem` under `context_servers` in `~/.config/zed/settings.json` |
+| Cursor | add `trailmem` under `mcpServers` in `~/.cursor/mcp.json` |
+| Windsurf | add `trailmem` under `mcpServers` in `~/.codeium/windsurf/mcp_config.json` |
+
+### Any other MCP agent
+
+Trailmem works with **any agent that speaks MCP** — Cursor, Windsurf, Cline, Zed, Gemini CLI, or anything newer. `trailmem integrate` only automates the hosts above; for everything else, register it yourself. You need exactly three facts:
+
+1. **Transport:** stdio (no URL, no port, no HTTP).
+2. **Command:** `trailmem-mcp` — no arguments, no environment variables required.
+3. **Server name:** `trailmem` (any name works; tool names don't depend on it).
+
+Most agents use a JSON block shaped like this (key name varies — `mcpServers`, `mcp`, `servers`):
+
+```json
+{
+  "mcpServers": {
+    "trailmem": {
+      "command": "trailmem-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If the agent can't find the command, use the absolute path — print it with:
+
+```bash
+which trailmem-mcp        # Windows: where trailmem-mcp
+```
+
+Then restart the agent and check the wiring: the agent should see six `trailmem_*` tools, and calling `trailmem_welcome` should return a briefing. `trailmem doctor` verifies the database side.
+
+### Updating
+
+```bash
+pip install --upgrade trailmem
+```
+
+There is no in-app "update available" notice — trailmem sends no telemetry, by design. Watch the GitHub Releases page instead.
+
+The agent then gets six tools: `trailmem_welcome` (once-per-session briefing), `trailmem_store`, `trailmem_query`, `trailmem_show`, `trailmem_edit`, `trailmem_link`. Everything is also available to humans via the `trailmem` CLI (`store`, `query`, `show`, `list`, `stats`, `link`, `archive`, ...).
+
+Try it from the CLI (note: `content` is positional; `--agent user` for your own notes):
+
+```bash
+trailmem store --title "First note" --type lesson --agent user "Something worth remembering."
+trailmem query "what did I note earlier"
+trailmem list
+trailmem help                # or: trailmem <command> --help
+```
+
+## Why
+
+- **Local-first.** One SQLite file (`~/.trailmem/trailmem.db`), WAL mode, no cloud, no daemon. Embeddings run locally via ONNX (default: bge-small-en-v1.5, user-swappable with `trailmem model use`).
+- **A graph, not a list.** Typed edges (`related`, `supersedes`, `evolves`, `contradicts`, `derived_from`), orphan warnings at store time, supersede chains instead of destructive overwrites.
+- **Token discipline.** Context is injected exactly once per session (welcome, ~600–800 tokens). No per-turn injection, ever. Repeat welcomes return a short form.
+- **No junk memories.** 4-band duplicate detection (exact hash reject → >0.92 block → 0.85–0.92 warn → accept), mandatory titles, hard-reject on unattributed stores, no auto-store lifecycle hooks.
+- **No telemetry.** The server writes only what the user needs (e.g. a local `hooks.log` diagnostic); it never emits analytics — a deliberate anti-goal, not an oversight.
+
+## Status
+
+Core implemented and tested (schema, store/dedup, query/show, welcome, MCP server, CLI, hooks, model management, loopback dashboard, host integration). Not yet published to PyPI. The design contract lives in [`docs/`](docs/index.md) — schema, welcome lifecycle, duplicate policy, evolution rules, CLI/MCP surfaces, hooks, seeding playbook, and the dashboard contract.
+
+## License
+
+MIT

trailmem-0.1.0/README.md

@@ -0,0 +1,98 @@
+# trailmem
+
+**Persistent, local-first graph memory for AI coding agents.**
+
+Trailmem gives agents durable cross-session memory without provider lock-in: a local SQLite knowledge graph, typed relationships, explicit knowledge evolution, and token-disciplined briefings. It is designed for multiple local agents—Claude, Kiro, Codex, OpenCode, Kilo, and Gemini—to share useful project knowledge without silently creating junk memories.
+
+## Quick start
+
+Same commands on Windows, macOS, and Linux (pure Python; wheels ship for all three). On some systems use `pip3` or `python -m pip` instead of `pip`.
+
+```bash
+pip install trailmem
+trailmem setup          # creates ~/.trailmem/, inits DB, downloads the default embedding model
+trailmem doctor         # health check
+
+# Register the MCP server with your agent host(s):
+trailmem integrate      # detects installed agent hosts, asks before writing any config
+```
+
+`trailmem integrate` auto-detects nine hosts: **Claude Code, Codex, Kiro, Kilo, OpenCode, Antigravity, Zed, Cursor, Windsurf**. It shows what it found, asks once (y/N), backs up every config it touches (`.bak-trailmem`), skips hosts that are already registered, and never rewrites a config it can't parse losslessly (JSONC with comments gets the manual entry printed instead).
+
+Prefer manual registration? Each host has its own mechanism:
+
+| Host | Manual registration |
+|------|--------------------|
+| Claude Code | `claude mcp add trailmem -- trailmem-mcp` |
+| Codex | add an `[mcp_servers.trailmem]` table to `~/.codex/config.toml` |
+| Kiro | add `trailmem` under `mcpServers` in `~/.kiro/settings/mcp.json` |
+| Kilo | add `trailmem` under `mcpServers` in `~/.config/kilo/kilo.jsonc` |
+| OpenCode | add `trailmem` under `mcp` in `~/.config/opencode/opencode.json` |
+| Antigravity | add `trailmem` under `mcpServers` in `~/.gemini/config/mcp_config.json` |
+| Zed | add `trailmem` under `context_servers` in `~/.config/zed/settings.json` |
+| Cursor | add `trailmem` under `mcpServers` in `~/.cursor/mcp.json` |
+| Windsurf | add `trailmem` under `mcpServers` in `~/.codeium/windsurf/mcp_config.json` |
+
+### Any other MCP agent
+
+Trailmem works with **any agent that speaks MCP** — Cursor, Windsurf, Cline, Zed, Gemini CLI, or anything newer. `trailmem integrate` only automates the hosts above; for everything else, register it yourself. You need exactly three facts:
+
+1. **Transport:** stdio (no URL, no port, no HTTP).
+2. **Command:** `trailmem-mcp` — no arguments, no environment variables required.
+3. **Server name:** `trailmem` (any name works; tool names don't depend on it).
+
+Most agents use a JSON block shaped like this (key name varies — `mcpServers`, `mcp`, `servers`):
+
+```json
+{
+  "mcpServers": {
+    "trailmem": {
+      "command": "trailmem-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+If the agent can't find the command, use the absolute path — print it with:
+
+```bash
+which trailmem-mcp        # Windows: where trailmem-mcp
+```
+
+Then restart the agent and check the wiring: the agent should see six `trailmem_*` tools, and calling `trailmem_welcome` should return a briefing. `trailmem doctor` verifies the database side.
+
+### Updating
+
+```bash
+pip install --upgrade trailmem
+```
+
+There is no in-app "update available" notice — trailmem sends no telemetry, by design. Watch the GitHub Releases page instead.
+
+The agent then gets six tools: `trailmem_welcome` (once-per-session briefing), `trailmem_store`, `trailmem_query`, `trailmem_show`, `trailmem_edit`, `trailmem_link`. Everything is also available to humans via the `trailmem` CLI (`store`, `query`, `show`, `list`, `stats`, `link`, `archive`, ...).
+
+Try it from the CLI (note: `content` is positional; `--agent user` for your own notes):
+
+```bash
+trailmem store --title "First note" --type lesson --agent user "Something worth remembering."
+trailmem query "what did I note earlier"
+trailmem list
+trailmem help                # or: trailmem <command> --help
+```
+
+## Why
+
+- **Local-first.** One SQLite file (`~/.trailmem/trailmem.db`), WAL mode, no cloud, no daemon. Embeddings run locally via ONNX (default: bge-small-en-v1.5, user-swappable with `trailmem model use`).
+- **A graph, not a list.** Typed edges (`related`, `supersedes`, `evolves`, `contradicts`, `derived_from`), orphan warnings at store time, supersede chains instead of destructive overwrites.
+- **Token discipline.** Context is injected exactly once per session (welcome, ~600–800 tokens). No per-turn injection, ever. Repeat welcomes return a short form.
+- **No junk memories.** 4-band duplicate detection (exact hash reject → >0.92 block → 0.85–0.92 warn → accept), mandatory titles, hard-reject on unattributed stores, no auto-store lifecycle hooks.
+- **No telemetry.** The server writes only what the user needs (e.g. a local `hooks.log` diagnostic); it never emits analytics — a deliberate anti-goal, not an oversight.
+
+## Status
+
+Core implemented and tested (schema, store/dedup, query/show, welcome, MCP server, CLI, hooks, model management, loopback dashboard, host integration). Not yet published to PyPI. The design contract lives in [`docs/`](docs/index.md) — schema, welcome lifecycle, duplicate policy, evolution rules, CLI/MCP surfaces, hooks, seeding playbook, and the dashboard contract.
+
+## License
+
+MIT

trailmem-0.1.0/docs/cli.md

@@ -0,0 +1,242 @@
+# trailmem — CLI Reference
+
+## Overview
+
+`trailmem` is the command-line interface for managing agent memory. All operations available via MCP tools are also available via CLI.
+
+**Installation:** `pip install trailmem`
+**Binary:** `trailmem`
+**Help:** `trailmem` (no args), `trailmem help`, or `trailmem --help` all print top-level help with usage examples and exit 0; `trailmem <command> --help` shows per-command flags.
+
+---
+
+## Commands
+
+### WRITE Operations
+
+```bash
+# Store a new memory
+trailmem store "content here" \
+    --title "Short Title" \
+    --type decision \
+    --agent kiro \
+    --pin \
+    --link-to mem-abc123 \
+    --edge-type related \
+    --work-type code-written \
+    --source "file:docs/apps/jarvis-play.md"
+# Also: --supersedes <ref> --archive-reason "why (min 20 chars)" for one-call supersede,
+#       --modified-files "a.py,b.py", --force to bypass the >0.92 near-dup block (exit 4)
+
+# Edit existing memory
+trailmem edit <ref> --content "updated content"
+trailmem edit <ref> --title "new title"
+trailmem edit <ref> --type lesson
+trailmem edit <ref> --pin            # or --no-pin
+trailmem edit <ref> --status archived --reason "why (min 20 chars)" --link-to <ref>
+
+# Archive (primary way to "remove" — preserves knowledge trail)
+trailmem archive <ref> --reason "replaced by QTcpSocket approach" --link-to <ref>
+
+# Link two memories
+trailmem link <source-ref> <target-ref> --type related --reason "both about aria2"
+
+# Remove a link
+trailmem unlink <edge-id>
+
+# Pin/unpin
+trailmem pin <ref>
+trailmem unpin <ref>
+```
+
+### READ Operations
+
+```bash
+# Show single memory (full detail + edges)
+trailmem show <ref>
+# Output: #id [node_id] title, type, agent, status, content, all edges
+
+# Search memories
+trailmem query "wayfire compositor"
+trailmem query "aria2" --type lesson
+trailmem query "build" --agent claude
+trailmem query "aria2" --limit 10 --format json   # default limit 5, text output
+
+# Session briefing (same as MCP welcome)
+trailmem welcome
+
+# Check near-duplicates before storing
+trailmem similar "content to check"
+# Shows: band (exact/0.92+/0.85+/low) + matching memory
+```
+
+### LIST Operations (filterable)
+
+```bash
+trailmem list                     # all active memories
+trailmem list --recent            # last 10, newest first
+trailmem list --orphans           # zero-edge memories
+trailmem list --pinned            # pinned + constraints
+trailmem list --tasks             # open tasks
+trailmem list --timeline          # grouped by day
+trailmem list --archived          # archived/superseded
+trailmem list --by-agent claude   # filter by agent
+trailmem list --project /path     # filter by project
+trailmem list --global            # only global (project=NULL)
+```
+
+### ADMIN Operations
+
+```bash
+# Statistics
+trailmem stats
+# Output: memory count, edge count, orphans, DB size, per-type breakdown
+
+# Maintenance (DRY-RUN by default — report only)
+trailmem maintain
+# Output: what would be cleaned (old sessions, orphan report)
+# Does NOT delete/archive anything without --apply
+
+trailmem maintain --apply
+# DESTRUCTIVE: purge sessions >90 days, report orphans
+# Confirmation prompt before execution
+# NEVER auto-archives/deletes memories
+
+# Backup & Restore
+trailmem export [output.json]      # full DB dump
+trailmem import <file.json> --merge    # add without overwriting existing
+trailmem import <file.json> --replace  # full overwrite (DOUBLE confirmation!)
+
+# Web Dashboard
+trailmem dashboard
+# Starts web UI at http://127.0.0.1:3800 (loopback-only, Ctrl-C to stop)
+# Flags: --port N | --project <path|global> | --agent <default attribution for UI-created memories>
+
+# Setup (first-time) — identical on Windows / macOS / Linux (pure-Python package)
+trailmem setup
+# Creates ~/.trailmem/, downloads the default embedding model, prints MCP registration hint.
+# Note: some systems use `pip3` or `python -m pip` instead of `pip`.
+
+# Integrate with agent hosts (auto-detect, permission-gated)
+trailmem integrate
+# Detects 9 hosts (Claude Code via `claude` on PATH; Codex / Kiro / Kilo / OpenCode /
+# Antigravity / Zed / Cursor / Windsurf
+# via their MCP config files) and, ONLY after an explicit y/N prompt, writes each host's
+# own MCP config. Per-host config differs: Claude Code uses `claude mcp add`; others get
+# their JSON config patched. No silent changes. (Manual fallback: `claude mcp add trailmem -- trailmem-mcp`.)
+# ANY other MCP agent works manually: stdio transport, command `trailmem-mcp`, no args/env.
+# README has the generic guide ("Any other MCP agent") with the common JSON shape + `which trailmem-mcp` for the absolute path.
+
+# Update to a newer release
+pip install --upgrade trailmem
+# No in-app "update available" notice (no telemetry, by design). Track GitHub Releases.
+
+# Health check
+trailmem doctor
+# Verifies: home + config presence, DB tables, sqlite-vec extension, embedding model
+```
+
+### MODEL Management (embedding model is user-configurable)
+
+```bash
+# List available + installed models
+trailmem model list
+
+# Install a supported model (checksum-verified download, NOT bundled in wheel)
+trailmem model install bge-small     # default (384-dim, good balance)
+trailmem model install minilm        # lighter (~200MB RAM)
+trailmem model install nomic         # better quality (768-dim, ~500MB RAM)
+trailmem model install --path /path/to/model.onnx   # custom ONNX; dims auto-detected at install and saved as dims.txt, no manual config edit
+
+# Switch active model
+trailmem model use nomic
+# Config updated. Dimensions may change → reindex required (see below).
+
+# Disable embeddings entirely → FTS5-only mode
+trailmem model disable
+# WARNING printed: semantic search OFF + near-duplicate detection OFF (exact-hash only)
+
+# Re-embed all memories with the current model
+# REQUIRED after `model use` when dimensions change (drops + recreates memories_vec)
+trailmem reindex
+# Also re-validates dedup bands against the new model's cosine distribution
+```
+
+Model config lives in `~/.trailmem/config.json`. Dedup thresholds (0.85/0.92) are per-model — swapping without `reindex` leaves stale bands. See [[schema]] embedding section and [[dedup]].
+
+### HIDDEN Commands (rare, destructive)
+
+```bash
+# Hard delete — permanent removal (NOT recommended, use archive instead)
+trailmem delete <ref> --hard --confirm
+# Warning: edges CASCADE delete, knowledge trail lost
+# Only for genuine junk/test data
+```
+
+---
+
+## Reference Resolution
+
+`<ref>` accepts both formats:
+- `4` or `#4` → lookup by memory ID
+- `mem-abc123` → lookup by node_id
+
+```bash
+trailmem show 4          # by ID
+trailmem show mem-abc123 # by node_id
+trailmem edit #4 --title "new"  # # prefix optional
+```
+
+---
+
+## Output Format
+
+Default: plain text (human + agent readable)
+```bash
+trailmem query "aria2"
+# #12 [mem-abc123] [decision] [claude] QTcpSocket for aria2 Communication
+#   Use QTcpSocket direct connection for aria2 JSON-RPC...
+# #7 [mem-def456] [lesson] [archived] Qt WebSocket Failed
+#   Connection drops under load, protocol mismatch...
+```
+
+JSON output (for dashboard/scripts):
+```bash
+trailmem list --format json
+trailmem export --format json
+```
+
+---
+
+## Environment Variables
+
+| Variable | Purpose | Auto-fill |
+|----------|---------|-----------|
+| `TRAILMEM_AGENT_TYPE` | Default agent_type | Auto-detects from CLAUDE_CODE_SESSION_ID etc |
+| `CLAUDE_CODE_SESSION_ID` | Session tracking | Claude Code sets this |
+| `KIRO_SESSION_ID` | Session tracking | Kiro sets this |
+| `TRAILMEM_DB` | Custom DB path | Default: ~/.trailmem/trailmem.db |
+| `TRAILMEM_HOME` | Custom home dir (config, models, DB, hooks.log) | Default: ~/.trailmem |
+| `TRAILMEM_PROJECT` | Override project detection (value global stores NULL for cross-project scope) | Default: cwd |
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Validation error (content too short, missing title, etc) |
+| 3 | Duplicate detected (exact hash match) |
+| 4 | Near-duplicate blocked (>0.92 similarity, use --force) |
+
+---
+
+## Related specs
+
+- [[mcp]] — the six MCP tools that share this CLI's validation/storage paths.
+- [[schema]] — data contracts; `model`/`reindex` commands map to the embedding config.
+- [[dedup]] — `similar` command + exit codes 3/4 behavior.
+- [[hooks]] — `trailmem hook session-start/session-stop` host integration.
+- [[migration]] — one-time seed runbook built on `store`/`link`.

trailmem-0.1.0/docs/dashboard.md

@@ -0,0 +1,141 @@
+# trailmem — Dashboard Specification
+
+**Status: built (2026-07-17), REVIEWED + HARDENED (2026-07-17, commit 4d862c6).** An initial `trailmem/dashboard.py` exists (authored by Amit, wired into cli.py). Audit + fresh-install functional test PASS: loopback-only bind, shared store/ops service layer (no direct SQLite writes), zero CDN/external assets, trigger-based revisioned SSE with Last-Event-ID replay + reset-on-gap, core validation on all write flows, no hard-delete in UI. Hardening added during review: Host/Origin loopback validation on every request (blocks DNS rebinding + cross-site CSRF), scope check on edge removal, clean port-in-use error. The dashboard is a first-party local feature, not a replacement for the six stdio MCP tools.
+
+## Product Goal
+
+`trailmem dashboard` should make a memory graph easy and comfortable to inspect, navigate, and maintain for long sessions. It must feel quiet while the data changes: a user reading a memory must never lose their scroll position, selected item, graph camera, layout, filter, or unfinished form because another agent stored a memory.
+
+The existing Omega dashboard is only a UX reference. Its five-second full polling and graph rebuild are explicitly rejected.
+
+## Boundary and Safety
+
+```bash
+trailmem dashboard
+# Local UI: http://127.0.0.1:3800
+```
+
+- Bind to loopback only by default; no public network listener in v1.
+- MCP remains **stdio-only**. The dashboard's loopback HTTP/SSE channel is an internal UI transport, not an HTTP MCP server or shared remote API.
+- The dashboard calls Trailmem's shared application/service layer. It must **never** write SQLite rows directly or duplicate store/edit/archive/link rules.
+- All dashboard writes use the same transactions, validation, model handling, deduplication, FTS/vector synchronization, archive rules, and orphan checks specified in [[schema]], [[dedup]], and [[evolution]].
+- Ship required frontend assets locally. The dashboard must remain usable offline and must not load analytics, fonts, scripts, or graph libraries from third-party CDNs.
+
+## Quiet Live-Update Contract
+
+### Initial data and revisions
+
+The first load receives a compact graph snapshot with a monotonic `revision`. Full content is fetched only for the selected memory. Each later write increases the revision after its database transaction commits.
+
+The UI subscribes to a local SSE stream. The server emits small change events, never a periodic full snapshot:
+
+```text
+id: 418
+event: memory.updated
+data: {"revision":418,"node_id":"mem-a1b2c3d4","changed":["title","status"]}
+```
+
+Required event kinds:
+
+| Event | Client action |
+|---|---|
+| `memory.created` | Add one node/list row without resetting the view. |
+| `memory.updated` | Patch that memory's summary; refresh its inspector only when it is not being edited. |
+| `memory.archived` | Patch status and dim the node; retain it in graph/search according to active filters. |
+| `memory.deleted` | Remove the node and its connected edges; show a quiet notice if it was selected. |
+| `edge.created` / `edge.deleted` | Patch only the affected edge counts, graph edge, and inspector links. |
+| `stats.updated` | Patch health/stat counters. |
+| `reset` | Request one fresh snapshot only when the client missed revisions or server history is unavailable. |
+
+Reconnect uses `Last-Event-ID`/`since_revision`. If the server cannot supply a complete event gap, it emits `reset`; this is the only permitted automatic full reload.
+
+### State that updates must preserve
+
+On every ordinary patch, preserve:
+
+- selected memory and inspector scroll position;
+- search text, filters, sort, active mode, and list scroll position;
+- graph zoom/pan camera and current in-browser node positions;
+- open dialogs and unsaved drafts;
+- keyboard focus and accessibility context.
+
+A tiny non-blocking “Synced” indicator may update; no toast, animation, or focus change is allowed for routine changes. If another agent edits the memory currently open in an unsaved form, show a passive conflict banner with explicit **Reload** and **Keep editing** choices. Never overwrite the user's draft.
+
+## Default Experience
+
+### Desktop layout
+
+Use a dense but breathable three-region workspace:
+
+1. **Top bar** — product name, project scope, search, connection state, and clickable health counters.
+2. **Graph canvas** — pan/zoom graph with readable labels only at useful zoom levels; visible type/status/edge meaning; keyboard-accessible selection.
+3. **Inspector** — full selected-memory content, metadata, archive/supersession context, and all inbound/outbound relationships.
+
+The inspector is the reading surface, not a cramped card list. Use comfortable line length, clear hierarchy, durable whitespace, selectable text, and obvious status contrast. Archived/superseded knowledge stays readable but visually subdued, never hidden by default.
+
+### Navigation and discoverability
+
+- Clicking a node selects it, centers it only when the user requests it, and opens its inspector.
+- Every relationship in the inspector is a clickable chip showing direction, type, `#id`, title, and optional reason. Clicking one selects and reveals that linked memory immediately.
+- Selecting a memory highlights its direct neighborhood without dimming the entire graph so heavily that labels become unreadable.
+- Search supports title/content/ID/node ID; filters include type, status, agent, project/global scope, pinned, and orphan state.
+- Health counters are actionable: clicking orphans, stale tasks, or contradictions applies the matching filter and explains the remediation path.
+- List/search results always show `#id`, `node_id` (or copy affordance), type, status, agent, edge count, and a restrained preview.
+
+### Graph behavior
+
+- Node color encodes type; shape, border, or badge distinguishes pinned/constraint, project/global scope, and archived/superseded status. Do not rely on color alone.
+- Edge styling differentiates relationship type and direction. Hover/focus reveals its reason/metadata.
+- New nodes appear without restarting the force simulation or moving existing nodes. Changed nodes preserve coordinates.
+- Provide an explicit **Re-layout graph** action with a confirmation/explanation. Automatic re-layout is prohibited.
+- The graph is an exploration aid, not the only way to work: an accessible list/inspector route remains fully usable without it.
+
+## Write Flows
+
+All mutations are explicit, validated, and reversible where the core supports it.
+
+- **Create:** requires title, English-oriented content check (soft warning), type, scope, attribution, and at least one meaningful link before final completion. The form surfaces duplicate/near-duplicate outcomes from [[dedup]] with links to the candidate record.
+- **Edit:** uses the core edit path and identifies fields changed by another writer before submit.
+- **Archive/supersede:** requires the reason and required relationship; ordinary UI does not offer hard delete.
+- **Link/unlink:** provides type, direction explanation, reason, duplicate prevention, and an orphan warning before an unlink creates one.
+- **Hard delete:** absent from normal dashboard UI; only the existing explicit CLI safety path may expose it.
+
+## Health and Feedback
+
+The dashboard must surface—not silently repair—data problems:
+
+- orphan memories;
+- stale open tasks;
+- unresolved contradiction edges;
+- model unavailable / FTS-only mode, including the loss of semantic search and near-duplicate detection;
+- database or event-stream connectivity problems.
+
+Errors are contextual and actionable. Successful routine saves update the affected UI in place; they do not trigger a full refresh.
+
+## Accessibility and Visual Quality
+
+- Support keyboard navigation, focus states, semantic controls, and screen-reader labels for graph/list/inspector actions.
+- Meet readable contrast in both light and dark themes; honor reduced-motion preferences.
+- Do not use attention-seeking animations. Motion is reserved for intentional navigation and must be subtle.
+- Responsive layouts may collapse the inspector into a focused view, but must preserve full-content reading and linked-memory navigation.
+
+## Implementation Gate and Open Decisions
+
+Before implementation, explicitly confirm these items rather than silently treating them as locked:
+
+1. **Position persistence:** v1 must preserve layout during a live session. Persisting node positions across browser restart (for example in local storage or a dedicated local table) is still an open choice.
+2. **Timeline mode:** graph + list/inspector are required; a dedicated timeline mode is deferred until approved.
+3. **Exact loopback API schema:** this document locks revision/SSE behavior and service-layer ownership, but endpoint names and payload fields need an implementation review against the final core model.
+4. **Authentication policy for non-loopback use:** v1 is loopback-only. Any LAN/remote mode requires a separate security design and explicit approval.
+
+## Acceptance Criteria
+
+Before dashboard release, demonstrate that:
+
+1. A second agent stores, edits, archives, links, and unlinks memories while a user reads another memory; the reader's state remains intact.
+2. No normal event calls a full graph render, restarts the simulation, or resets the graph camera.
+3. A dropped SSE connection catches up by revision or performs one controlled `reset` reload.
+4. All writes pass the same core validations as CLI/MCP, including archive and orphan rules.
+5. Every visible relationship is keyboard-accessible and clickable to its connected memory.
+6. The dashboard works offline with no third-party runtime requests.
+7. Graph-disabled or assistive-technology users can search, inspect, and maintain memories through the list/inspector workflow.