|
| 1 | +# `mempalace-source-omoa` — design note |
| 2 | + |
| 3 | +- **Date:** 2026-05-26 |
| 4 | +- **Tracker:** [techempower-org/mempalace#38](https://github.com/techempower-org/mempalace/issues/38) |
| 5 | +- **Source RFC:** [RFC 002 — Source Adapter Plugin Specification](../rfcs/002-source-adapter-plugin-spec.md) |
| 6 | +- **Companion note:** [opencode RLM gap analysis](2026-05-26-opencode-rlm-gap-analysis.md) |
| 7 | +- **Status:** Planning. No code in this round. |
| 8 | + |
| 9 | +## Summary |
| 10 | + |
| 11 | +`code-yeongyu/oh-my-openagent` (omoa, formerly oh-my-opencode) is a TypeScript plugin layered on top of OpenCode. Its session storage is **identical** to bare OpenCode's — the SQLite database at `~/.local/share/opencode/opencode.db` — which means the existing [`OpenCodeSourceAdapter`](../../mempalace/sources/opencode.py) already covers omoa session ingestion with zero new code. |
| 12 | + |
| 13 | +What omoa adds on top of OpenCode is a set of **project-tree artifacts** that hold curated context: `.omo/tasks/*.json`, hierarchical `AGENTS.md` files, learnings (location TBD per omoa's still-evolving #1397 spec), `.claude/skills/*/SKILL.md`, and `.claude/rules/*.md`. These are not session content; they are durable knowledge artifacts that a future omoa session reads to start with context. A second adapter, `mempalace-source-omoa`, mines those. |
| 14 | + |
| 15 | +This note specifies the second adapter. Effort estimate: **M** (~1-2 days of work). |
| 16 | + |
| 17 | +## Background — what omoa stores where |
| 18 | + |
| 19 | +Confirmed against the omoa README, the `.opencode/opencode.json` plugin entry, and the [feature reference](https://github.com/code-yeongyu/oh-my-openagent/blob/dev/docs/reference/features.md): |
| 20 | + |
| 21 | +| Artifact | Path (project-relative) | Format | Lifecycle | |
| 22 | +|---|---|---|---| |
| 23 | +| Session transcripts | `~/.local/share/opencode/opencode.db` (user-scope SQLite) | OpenCode SQLite schema (`session` / `message` / `part`) | Append-only on every assistant turn | |
| 24 | +| Task state | `.omo/tasks/T-<uuid>.json` | JSON per task | Created/updated by omoa task tools | |
| 25 | +| Hierarchical context | `AGENTS.md` (root + nested under `src/**/`) | Markdown | Updated by `/init-deep` and human edits | |
| 26 | +| Skills | `.opencode/skills/<name>/SKILL.md`, `.claude/skills/<name>/SKILL.md`, `.agents/skills/<name>/SKILL.md` | Markdown with frontmatter | Hand-authored or generated | |
| 27 | +| Commands | `.opencode/command/*.md`, `.claude/commands/*.md` | Markdown | Hand-authored | |
| 28 | +| Conditional rules | `.claude/rules/*.md(c)` | Markdown with frontmatter (`globs`, `alwaysApply`) | Hand-authored | |
| 29 | +| Hook config | `.claude/settings.json`, `.claude/settings.local.json` | JSON | Hand-authored | |
| 30 | +| Plugin config | `oh-my-openagent.jsonc` (or legacy `oh-my-opencode.jsonc`) | JSONC | Hand-authored | |
| 31 | +| Learnings (proposed #1397) | `.sisyphus/learnings/{session}.jsonl` | JSONL | Append-only via `/capture-learning` | |
| 32 | + |
| 33 | +**Sessions are out of scope for this adapter.** The existing `OpenCodeSourceAdapter` already maps `~/.local/share/opencode/opencode.db` → drawers. The omoa adapter focuses on the project-tree artifacts above. |
| 34 | + |
| 35 | +## Why a separate adapter, not an `omo` mode on the existing one |
| 36 | + |
| 37 | +The existing OpenCode adapter is keyed on a user-scope SQLite path; it has no concept of a project tree. The omoa artifacts are keyed on project root and live across many trees. They share no source format, no chunking strategy, and no `is_current` shape. Per RFC 002 §1 the natural split is "one adapter per source surface" — bundling them would force every omoa user to also enable bare-OpenCode mining and vice versa. |
| 38 | + |
| 39 | +Both adapters compose: a user with omoa enabled mines twice — once via `opencode` (session content) and once via `omoa` (project context). The two adapters use distinct `source_file` URI shapes so drawers do not collide. |
| 40 | + |
| 41 | +## Adapter contract |
| 42 | + |
| 43 | +### Identity |
| 44 | + |
| 45 | +```python |
| 46 | +class OmoaSourceAdapter(BaseSourceAdapter): |
| 47 | + name = "omoa" |
| 48 | + adapter_version = "0.1.0" |
| 49 | + capabilities = frozenset({ |
| 50 | + "supports_incremental", # mtime-based, see §is_current |
| 51 | + "supports_structured_metadata", |
| 52 | + "adapter_owns_routing", |
| 53 | + }) |
| 54 | + supported_modes = frozenset({"whole_record"}) |
| 55 | + declared_transformations = frozenset({ |
| 56 | + "newline_normalize", |
| 57 | + "whitespace_trim", |
| 58 | + # No content-altering transforms — markdown and JSON go through verbatim. |
| 59 | + # JSON is reformatted only if the source is whitespace-divergent; |
| 60 | + # the round-trip suite verifies `json.loads(content) == json.loads(source_bytes)`. |
| 61 | + }) |
| 62 | + default_privacy_class = "pii_potential" |
| 63 | +``` |
| 64 | + |
| 65 | +### `SourceRef` shape |
| 66 | + |
| 67 | +```python |
| 68 | +SourceRef(local_path="/home/user/project") # project root containing .omo/, .claude/, etc. |
| 69 | +``` |
| 70 | + |
| 71 | +Default behavior: discover artifacts beneath the project root using a fixed glob set (below). Operator MAY pass `options={"include_user_scope": True}` to also mine `~/.claude/`, `~/.config/opencode/`, `~/.agents/` — disabled by default because user-scope artifacts often belong in a different wing than the project they were used from. |
| 72 | + |
| 73 | +### Discovery globs (v1) |
| 74 | + |
| 75 | +``` |
| 76 | +{root}/.omo/tasks/T-*.json |
| 77 | +{root}/AGENTS.md |
| 78 | +{root}/**/AGENTS.md # truncated at depth 6 to avoid build-output trees |
| 79 | +{root}/.opencode/skills/*/SKILL.md |
| 80 | +{root}/.opencode/command/*.md |
| 81 | +{root}/.claude/skills/*/SKILL.md |
| 82 | +{root}/.claude/commands/*.md |
| 83 | +{root}/.claude/rules/*.md |
| 84 | +{root}/.claude/rules/*.mdc |
| 85 | +{root}/.agents/skills/*/SKILL.md |
| 86 | +{root}/oh-my-openagent.jsonc # plus the .json / oh-my-opencode legacy basenames |
| 87 | +{root}/.claude/settings.json |
| 88 | +{root}/.claude/settings.local.json |
| 89 | +{root}/.sisyphus/learnings/*.jsonl # if/when omoa #1397 lands; gated by file existence |
| 90 | +``` |
| 91 | + |
| 92 | +The adapter walks each matched path and yields one `DrawerRecord` per file. JSONL files (`.sisyphus/learnings/*.jsonl` and `.omo/tasks/*.json` if it becomes JSONL) yield one drawer per line; the line is the drawer content, with line-number metadata. |
| 93 | + |
| 94 | +`.gitignore` is respected: the adapter skips paths that match the project's gitignore so build outputs and ephemeral state are not mined. |
| 95 | + |
| 96 | +### `source_file` URI shape |
| 97 | + |
| 98 | +``` |
| 99 | +omoa://<project-root-absolute>/<relative-path-from-root> |
| 100 | +omoa://<project-root-absolute>/<relative-path-from-root>#line=<n> # for JSONL |
| 101 | +``` |
| 102 | + |
| 103 | +Stable across re-ingests; used as the ChromaDB `where={"source_file": ...}` key for `is_current` lookup. |
| 104 | + |
| 105 | +### Routing (§2.5) |
| 106 | + |
| 107 | +Three-tier precedence per RFC 002: |
| 108 | + |
| 109 | +1. Explicit `options["wing"]` from the `SourceRef`. |
| 110 | +2. Project-root basename (sanitized via `normalize_wing_name`). |
| 111 | +3. Adapter fallback: `"omoa_general"`. |
| 112 | + |
| 113 | +Room detection per artifact kind: |
| 114 | + |
| 115 | +| Artifact kind | Room | |
| 116 | +|---|---| |
| 117 | +| `AGENTS.md` and nested | `context` | |
| 118 | +| `.omo/tasks/T-*.json` | `tasks` | |
| 119 | +| Skills (any path) | `skills` | |
| 120 | +| Commands | `commands` | |
| 121 | +| Rules | `rules` | |
| 122 | +| Config (jsonc, settings.json) | `config` | |
| 123 | +| Learnings (when present) | `learnings` | |
| 124 | + |
| 125 | +Hall: deferred to `convo_miner._detect_hall_cached` if room ends up generic; otherwise adapter sets hall explicitly to the artifact kind. |
| 126 | + |
| 127 | +### Per-drawer metadata schema (§5.2) |
| 128 | + |
| 129 | +```python |
| 130 | +def describe_schema(self) -> AdapterSchema: |
| 131 | + return AdapterSchema( |
| 132 | + version="1.0", |
| 133 | + fields={ |
| 134 | + "project_root": FieldSpec( |
| 135 | + type="string", required=True, indexed=True, |
| 136 | + description="Absolute path of the project root at ingest time", |
| 137 | + ), |
| 138 | + "artifact_kind": FieldSpec( |
| 139 | + type="string", required=True, indexed=True, |
| 140 | + description=( |
| 141 | + "One of: agents_md, task, skill, command, rule, " |
| 142 | + "config, learning" |
| 143 | + ), |
| 144 | + ), |
| 145 | + "relative_path": FieldSpec( |
| 146 | + type="string", required=True, |
| 147 | + description="Path relative to project_root (POSIX separators)", |
| 148 | + ), |
| 149 | + "source_mtime": FieldSpec( |
| 150 | + type="string", required=True, |
| 151 | + description="ISO-8601 UTC of source file mtime at ingest", |
| 152 | + ), |
| 153 | + "source_size_bytes": FieldSpec( |
| 154 | + type="int", required=True, |
| 155 | + description="Size of source file in bytes", |
| 156 | + ), |
| 157 | + "frontmatter_json": FieldSpec( |
| 158 | + type="json_string", required=False, |
| 159 | + description=( |
| 160 | + "Parsed YAML frontmatter for skill/rule artifacts " |
| 161 | + "(globs, alwaysApply, name, description)" |
| 162 | + ), |
| 163 | + ), |
| 164 | + "jsonl_line_no": FieldSpec( |
| 165 | + type="int", required=False, |
| 166 | + description="1-indexed line number for JSONL-derived drawers", |
| 167 | + ), |
| 168 | + }, |
| 169 | + ) |
| 170 | +``` |
| 171 | + |
| 172 | +### Incremental ingest (`is_current`) |
| 173 | + |
| 174 | +```python |
| 175 | +def is_current(self, *, item: SourceItemMetadata, existing_metadata: Optional[dict]) -> bool: |
| 176 | + if not existing_metadata: |
| 177 | + return False |
| 178 | + stored = existing_metadata.get("source_mtime") |
| 179 | + return stored == item.version # version == source_mtime ISO-8601 |
| 180 | +``` |
| 181 | + |
| 182 | +For JSONL artifacts, `version` includes the line count so an append at the tail invalidates the file cleanly without re-ingesting earlier lines (the lines that already exist are addressed by `source_file` with `#line=` and skipped individually). |
| 183 | + |
| 184 | +## Verbatim guarantee (§1.4) |
| 185 | + |
| 186 | +- Markdown files (`AGENTS.md`, skills, commands, rules) yield drawers whose `content` is the file's exact UTF-8 bytes after `newline_normalize` + `whitespace_trim`. The declared transformations are byte-checkable; the round-trip suite confirms `re_normalize(content) == re_normalize(original)`. |
| 187 | +- JSON files (`.omo/tasks/*.json`, settings.json) yield drawers whose `content` is the file's exact text. The conformance check is `json.loads(content) == json.loads(original)` (structural equality — whitespace-only divergence is allowed because we want grep-friendly content, not byte-identical roundtrip). |
| 188 | +- JSONL files yield one drawer per line. `content` is the line's exact text (no JSON re-encoding). |
| 189 | +- No summarization, no LLM-assisted extraction, no `learning.type` re-classification. The omoa #1397 spec proposes classification *at capture time inside omoa*; MemPalace ingests whatever omoa wrote, as-is. If omoa later changes its learning schema, we mine the new shape verbatim and the schema lives in omoa's `LearningEntry` JSON, not ours. |
| 190 | + |
| 191 | +This matches `CLAUDE.md` §"Verbatim always": the structured metadata an omoa user might want to filter on (`type=anti-pattern`, `target=AGENTS.md`) lives in the per-line JSON content — searchable via `mempalace_search` keyword match against the verbatim line. |
| 192 | + |
| 193 | +## Privacy and gitignore handling |
| 194 | + |
| 195 | +- Default `privacy_class`: `pii_potential`. Project-tree config files routinely contain user/host/repo names, API keys (in violation but real), absolute home paths. An operator MAY override via `options={"privacy_class": "secrets_possible"}` to gate against the upcoming [#389](https://github.com/MemPalace/mempalace/pull/389) sensitive-content scanner. |
| 196 | +- The adapter respects `.gitignore`. `.claude/settings.local.json` is conventionally gitignored and SHOULD be mined only when the operator passes `options={"include_gitignored": True}` because secrets land there. Default: skip. |
| 197 | +- `~/.config/opencode/mcp-oauth.json` (chmod 0600 in the omoa docs) is **never** mined regardless of options, because it holds OAuth tokens. The adapter hard-skips any file matching `*oauth*.json` or `*credentials*` under the OpenCode/Claude config paths. |
| 198 | + |
| 199 | +## Composition with the existing OpenCode adapter |
| 200 | + |
| 201 | +A user with both adapters enabled and a project at `/home/jp/Projects/example`: |
| 202 | + |
| 203 | +```bash |
| 204 | +mempalace mine --source opencode # all sessions, user-scope |
| 205 | +mempalace mine --source omoa /home/jp/Projects/example # this project's context |
| 206 | +``` |
| 207 | + |
| 208 | +Drawers from the two adapters never collide: |
| 209 | + |
| 210 | +| Adapter | `source_file` URI prefix | |
| 211 | +|---|---| |
| 212 | +| `opencode` | `opencode://~/.local/share/opencode/opencode.db#session=ses_...` | |
| 213 | +| `omoa` | `omoa:///home/jp/Projects/example/AGENTS.md` | |
| 214 | + |
| 215 | +A `mempalace_search` over both yields verbatim hits ranked by semantic similarity: the agent gets *what was said* (sessions) and *what was decided* (project context) in one query. |
| 216 | + |
| 217 | +## Open questions |
| 218 | + |
| 219 | +1. **`AGENTS.md` chunking.** Long `AGENTS.md` files (the omoa example trees regularly hit 2-3K lines) may want section-level chunking, not whole-record. The first-party `convo_miner.chunk_exchanges` does exchange-pair chunking which doesn't fit. Proposed v1: whole-record (one drawer per file); revisit if drawers blow past Chroma's per-document soft ceiling or search precision suffers. |
| 220 | +2. **`.omo/tasks/*.json` vs `~/.omo/`.** omoa's task system is project-local in `.omo/tasks/`, but the README hints at a user-scope `~/.omo/` for cross-project context. Verify against omoa source before v1 — if user-scope tasks exist, they belong behind the same `include_user_scope` flag. |
| 221 | +3. **omoa #1397 lock-in.** The learning-capture spec is still draft / community-review. We should hold off mining `.sisyphus/learnings/*.jsonl` until omoa pins the schema. v1 ships without learnings support and adds it on follow-up PR. |
| 222 | +4. **Rename transition.** omoa is dual-publishing as `oh-my-opencode` and `oh-my-openagent` during the rename. The adapter should recognize both `oh-my-opencode.jsonc` and `oh-my-openagent.jsonc` as the same artifact kind (`config`) — handled in the discovery glob list above. |
| 223 | +5. **Should this live in-tree or as a separate `mempalace-source-omoa` package?** RFC 002 says third parties ship as `pip install mempalace-source-<name>`, and omoa is third-party. But the same RFC also recognizes "first-party adapters that ship in core" (filesystem, conversations, opencode, codex, gemini, aider, warp). Given that omoa-on-OpenCode is the closest analogue to Claude-Code-on-Anthropic and we already ship the bare OpenCode adapter in-tree, ship `omoa` in-tree too. A separate package adds release friction without buying isolation. |
| 224 | + |
| 225 | +## Effort estimate |
| 226 | + |
| 227 | +| Item | Effort | Notes | |
| 228 | +|---|---|---| |
| 229 | +| Adapter skeleton + discovery + verbatim emit | S (~3h) | Mirrors `mempalace/sources/filesystem.py` | |
| 230 | +| `is_current` for files + JSONL append handling | S (~2h) | mtime check + JSONL line slicing | |
| 231 | +| `describe_schema` + frontmatter extraction for skills/rules | S (~2h) | Reuse `python-frontmatter` if already a dep | |
| 232 | +| Conformance suite (RFC 002 §7 round-trips) | M (~3h) | Markdown byte-roundtrip + JSON structural equality | |
| 233 | +| Integration with `mempalace mine` CLI (`--source omoa`) | XS (~30 min) | Entry-point registration | |
| 234 | +| Docs: `docs/integrations/omoa.md` modelled on the opencode doc | S (~2h) | | |
| 235 | +| **Total** | **M (~12h, ~1.5 days)** | Single contributor | |
| 236 | + |
| 237 | +## Next steps if approved |
| 238 | + |
| 239 | +1. File a follow-up PR implementing `mempalace/sources/omoa.py` + tests + entry-point + docs. |
| 240 | +2. Add a `docs/fork-changes.yaml` entry for fork-ahead inventory. |
| 241 | +3. Hold the discussion #1277 reply until both opencode (already done) and omoa (this PR) are shippable — per [`feedback_upstream_comment_timing.md`](https://github.com/jphein/) (private memory). |
| 242 | +4. Open an issue against omoa to confirm task-storage paths (`~/.omo/` vs `.omo/`) and learnings schema timing. |
| 243 | + |
| 244 | +## References |
| 245 | + |
| 246 | +- omoa repo: <https://github.com/code-yeongyu/oh-my-openagent> (default branch `dev`) |
| 247 | +- omoa feature reference: <https://github.com/code-yeongyu/oh-my-openagent/blob/dev/docs/reference/features.md> |
| 248 | +- omoa learning capture proposal: <https://github.com/code-yeongyu/oh-my-openagent/issues/1397> |
| 249 | +- The existing OpenCode adapter (which already covers omoa sessions): [`mempalace/sources/opencode.py`](../../mempalace/sources/opencode.py) |
| 250 | +- RFC 002 spec text: [`docs/rfcs/002-source-adapter-plugin-spec.md`](../rfcs/002-source-adapter-plugin-spec.md) |
| 251 | +- Companion note: [`2026-05-26-opencode-rlm-gap-analysis.md`](2026-05-26-opencode-rlm-gap-analysis.md) |
0 commit comments