Skip to content

Commit 899fdfb

Browse files
authored
docs(integration): design notes for opencode + oh-my-openagent source adapters (#38) (#232)
* docs(integration): design notes for opencode + omoa source adapters (#38) Two planning notes responding to #38 — the discussion-MemPalace#1277 commitment to evaluate opencode + oh-my-openagent integration: - 2026-05-26-opencode-rlm-gap-analysis.md: maps the three TomLucidor issues to MemPalace surface. anomalyco/opencode#8554 and #11829 are RLM (Recursive Language Model) proposals — orthogonal to MemPalace's cross-session verbatim store; the existing OpenCodeSourceAdapter is unchanged by them and composes cleanly via MCP. omoa#1397 is a learning-capture-into-AGENTS.md proposal — complementary, not substitutable; its session storage is OpenCode SQLite which we already cover. - 2026-05-26-mempalace-source-omoa.md: design note for a future mempalace-source-omoa adapter targeting omoa's project-tree artifacts (.omo/tasks/, AGENTS.md hierarchy, skills, rules, commands). Sessions remain covered by the existing OpenCode adapter. Two adapters compose via distinct source_file URI prefixes. Effort estimate: M (~1.5 days). Open questions enumerated. Read-only research round per the team-lead brief. No code changes. No upstream discussion comment yet — deferring per the upstream-comment-timing rule until omoa adapter has shippable code. * docs(integration): wrap bare URLs in angle brackets to pass markdownlint MD034/no-bare-urls. References section in the omoa design note had three bare URLs on lines 246-248; wrap them in <...> to make markdownlint happy. No content change.
1 parent a5a3a06 commit 899fdfb

2 files changed

Lines changed: 357 additions & 0 deletions

File tree

Lines changed: 251 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,251 @@
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

Comments
 (0)