Joakim Persson
954c3f2ebb
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.
80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
# 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.
|