Initial commit — split out from cli_utils

Producer-side MemPalace tooling: two bash wrappers that bridge opencode
session history and project documentation into the palace. Originally
developed in cli_utils (2026-04-28); split into its own repo on
2026-04-30 because the conceptual fit was weak — cli_utils is
interactive shell tooling, while this is agent memory infrastructure
with its own architecture, dependency surface, and growth trajectory.

Contents:
- bin/mempalace-docs — docs-only mining wrapper (originally a2ddcc9 in
  cli_utils), bridges the gap until MemPalace PR #1213 (exclude_patterns)
  merges upstream.
- bin/mempalace-session — opencode → palace session bridge (originally
  dacca0e in cli_utils). Reads ~/.local/share/opencode/opencode.db,
  exports each session to Claude Code JSONL, mines via
  'mempalace mine --mode convos'. Bridges the gap until opencode
  session-stopping hooks + an opencode harness in hooks_cli.py land
  upstream.
- ARCHITECTURE.md — canonical spec: architecture diagram, component
  details, setup recipe, operational notes, upstream-retirement
  roadmap. Originally a4cf314 in cli_utils.
- SKILL.md — companion agent skill (producer side). Pairs with the
  consumer-side mempalace skill. Symlinked into
  ~/.agents/skills/opencode-mempalace-bridge/ by install.sh.
- install.sh — idempotent installer, also handles --uninstall.
- AGENTS.md — repo conventions.

History of the individual files is not preserved in this split; see
cli_utils (gitea.jordbo.se/joakimp/cli_utils) commits a2ddcc9, dacca0e,
and a4cf314 for the original authorship context.

AGENTS.md

@@ -0,0 +1,79 @@
+# AGENTS.md
+
+## What this is
+
+Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace). Two thin wrappers in `bin/` plus the companion agent skill. Pairs with the consumer-side `mempalace` skill.
+
+Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first — it's the canonical spec for what this repo does and why.
+
+## Structure
+
+```
+install.sh              # Idempotent installer — symlinks bin/* into ~/.local/bin
+                        # and SKILL.md into ~/.agents/skills/opencode-mempalace-bridge/
+ARCHITECTURE.md         # Canonical spec: diagrams, setup recipe, ops notes, upstream roadmap
+README.md               # Human-facing quickstart + per-tool usage reference
+SKILL.md                # Agent skill (symlinked into ~/.agents/skills/ on install)
+bin/
+  mempalace-docs        # Docs-only MemPalace miner (bash wrapper)
+  mempalace-session     # Opencode session → MemPalace bridge (bash + inline Python)
+```
+
+## Conventions
+
+- **Standalone executables** in `bin/` with `#!/usr/bin/env bash` shebang, no extension, `chmod +x`. Must work in non-interactive contexts (agent processes, cron, CI).
+- **Thin wrappers only.** Neither tool reimplements the mempalace miner. Both follow the **stage-to-cache-then-mine** idiom: curate input to `~/.cache/…/<wing>/`, then delegate to `mempalace mine`.
+- **Idempotent + dry-runnable.** Every tool supports `--dry-run`. Second invocation on unchanged input is a no-op (dedup via `source_file` path, optionally + `mtime`).
+- **No external Python deps.** Stdlib only (`sqlite3`, `json`, `pathlib`). Inline in the bash wrapper via heredoc.
+- Argument parsing: `--help`/`-h` first, then mode flags, then positional args.
+- Comment sections use `# ── Section Name ──────` style (matches sibling `cli_utils` repo).
+
+## Adding a new wrapper
+
+A third wrapper would justify factoring a shared helper library. Until then, copy the pattern from `mempalace-session` (richest example):
+
+1. Create `bin/<name>` with `#!/usr/bin/env bash` + `chmod +x`.
+2. Implement `--help`, `--dry-run`, `--no-repair` flags.
+3. Stage to `~/.cache/<name>/<wing>/` with deterministic filenames.
+4. Invoke `mempalace mine ...` (choose `--mode convos` if input is chat-like).
+5. End with `mempalace repair` unless `--no-repair`.
+6. Update `README.md` with usage + rationale.
+7. Update `install.sh`? No — `bin/*` is auto-linked.
+8. Update `ARCHITECTURE.md` if the wrapper fills a new architectural gap.
+9. Update `SKILL.md` if agents should know when to invoke it.
+
+## Testing
+
+Manual only. Integration-shaped:
+
+```bash
+# Smoke test — does it parse args and list what would happen?
+./bin/mempalace-session --help
+./bin/mempalace-session --dry-run
+
+# Real test on a single session (safe, deterministic)
+./bin/mempalace-session --session ses_<id> --dry-run
+./bin/mempalace-session --session ses_<id>     # file into palace
+mempalace_search "a phrase from that session"   # verify visibility
+./bin/mempalace-session --session ses_<id>     # re-run → should skip
+```
+
+For `mempalace-docs`, test on a small repo (e.g. this one) first:
+
+```bash
+./bin/mempalace-docs "$PWD" --dry-run
+```
+
+## Gotchas
+
+- `install.sh` is idempotent but interactive — use `--yes` in non-interactive contexts.
+- `~/.local/bin` must be on `$PATH`. The installer warns if not.
+- The companion skill lives at `~/.agents/skills/opencode-mempalace-bridge/SKILL.md` and is a **symlink into this repo**. Editing that file edits `SKILL.md` here. To propagate to Claude Code / Kiro, run `agents-sync` from [`cli_utils`](https://gitea.jordbo.se/joakimp/cli_utils).
+- The opencode DB path defaults to `~/.local/share/opencode/opencode.db`. Override via `$OPENCODE_DB` or `--db`.
+- The mempalace miner **skips symlinks** (as of v3.3.3 — `miner.py` line ~828). That's why the wrappers use `cp -p` / explicit file writes for staging, not symlinks.
+- The convos miner dedups on `source_file` path only (no mtime check). Staging filenames must be stable per session; deleting a staged JSONL forces a re-mine.
+- The docs miner dedups on `source_file` path + `mtime`. That's why staging uses `cp -p` (preserves mtime).
+
+## History
+
+Split out from [`cli_utils`](https://gitea.jordbo.se/joakimp/cli_utils) on 2026-04-30. The wrappers originated there but the conceptual fit was weak (`cli_utils` is interactive shell tools; these are agent memory infrastructure). Some older diary entries and KG facts in the palace reference the original paths.