docs: add plan to simplify OpenPalm via akm-cli + shared stash#381
Open
itlackey wants to merge 7 commits into
Open
docs: add plan to simplify OpenPalm via akm-cli + shared stash#381itlackey wants to merge 7 commits into
itlackey wants to merge 7 commits into
Conversation
Captures the proposed simplification: drop the memory service, the OpenViking addon, and varlock; fold the scheduler into the assistant container; install akm in guardian/assistant/admin and share the stash via a host bind-mount. Each capability gap is mapped to a scheduled automation or an assistant OpenCode plugin tool. https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
Splits the gap shims from the simplification plan into two upstream buckets: general-purpose enhancements for akm-cli (memory --infer, scope flags, feedback on memory refs, events/history, akm serve, vault backends, graph build, scheduled workflows, shared LLM config) and harness-coupled enhancements for akm-plugins (session.created retrieval, scope auto-attach, conversation-derived feedback, session-end consolidation via --infer, per-thread overlays, opencode/claude parity). https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
Stack:
- Admin and assistant share ${OP_HOME}/data/stash; guardian gets its own
${OP_HOME}/data/guardian-stash so channel-secret data is not visible
to user-facing services.
- Collapse the memory-enrich and memory-graph automations into a single
akm-index automation; akm's index process handles both passes when
configured upstream.
Upstream akm-cli:
- Memory inference moves into the index process, controlled by global
config (no --infer flag); same pattern for graph build.
- akm feedback should accept any valid ref, not just memory/vault.
- Vault backend pluggability deferred (future consideration).
- Drop akm events, akm history, akm serve, and akm workflow schedule
proposals; documented as explicit non-goals.
Upstream akm-plugins:
- Drop the per-thread stash overlay proposal.
- Session-end consolidation reframed as an optional akm index call.
- Add a harness-provided LLM fallback so plugins can lend their provider
connection to akm's index passes when akm has no LLM configured.
https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
Stack:
- Drop the scheduler HTTP API entirely. Admin already mounts
${OP_HOME}/config rw and writes automation YAML directly; the
scheduler subprocess inside the assistant container watches the
directory. Manual triggers use sentinel files under
${OP_HOME}/data/scheduler/triggers/. Execution logs come from the
shared ${OP_HOME}/logs/ mount admin already has.
- No port 8090 exposure anywhere; no admin -> scheduler token.
Upstream akm-cli:
- Restore akm events (append-only events.jsonl + list/tail) and akm
history (per-asset and stash-wide) as proposals, with renumbered
upstream items.
- Update the History gap row to call akm history directly instead of
shelling git log against the stash.
- Explicitly-not-proposed list shrinks to akm serve and akm workflow
schedule.
https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
Adds ready-to-file issue drafts under docs/plans/upstream-issues/, split by destination repo: - akm-cli-issues.md: 8 issues (index-time inference, scoping flags, feedback-on-any-ref, akm events, akm history, vault backends, index-time graph, unified akm.llm config) plus the explicit non-goals. - akm-plugins-issues.md: 6 issues (session.created retrieval, scope auto-attach, conversation-derived feedback, session-end index, harness-provided LLM fallback, parity meta-issue). Each block has a suggested title, labels, body, and acceptance criteria so they can be pasted into the upstream tracker as-is. https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
Reality-checked against akm-cli 0.7.4 and akm-opencode 0.7.3 (live
GitHub state, 2026-05-06). Many earlier upstream proposals have
already shipped:
CLI: akm index --enrich (memory inference + graph extraction),
akm events list/tail, akm history --include-proposals,
akm feedback on memory:/vault: refs, scope flags on
akm remember, akm proposal/reflect/propose/distill verbs,
lesson asset type.
Plugin: AKM_INDEX_ON_SESSION_END, AKM_CONTEXT_BUDGET_CHARS,
AKM_SCOPE_KEYS, AKM_RETROSPECTIVE_NEGATIVE_PATTERN.
Plan updates:
- Context section now targets 0.7.x and notes that
akm-opencode no longer auto-installs the CLI.
- Gap -> resolution table replaces every "via OpenPalm shim" entry
with a direct call to the existing 0.7.x feature.
- New row: agent-proposed changes review via akm propose / akm proposal.
Upstream drafts collapsed:
- akm-cli: 8 issues -> 3 (LLM-proxy hook, vault backends future, scope-
flag inconsistency bug). Adds a "Already shipped" appendix.
- akm-plugins: 6 issues -> 4 (LLM-proxy shim, stale feedback guard
bug, buildScopedArgs() shape bug, parity meta).
https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
A second simplification pass that targets the operator-facing surface beyond the akm migration in simplify-via-akm.md. The new doc records: a config + mounts audit (~100 env vars, ~17 port/bind pairs, 4 varlock-shaped schema files, an init helper that just chowns dirs, an empty config/guardian/), a four-perspective debate (security, SRE, UX, maintainer) with tensions resolved, 34 numbered recommendations grouped by surface (env vars, mounts, vault layout, setup wizard, lifecycle, docs), explicit non-changes that protect the trust model, and a phased implementation order. Headline reductions when the recommendations land: - ~60-70 env vars dropped (OP_CAP_* family, port-pair collapse, vault user migration to akm, owner info to akm, sentinel cleanup). - 4 .env.schema files deleted with varlock. - init container removed; replaced by entrypoint chown. - 5 technical docs and the README rewritten away from memory/scheduler/varlock/openviking. Aligns simplify-via-akm.md with this pass: - Adds package.json workspace cleanup, e2e-test deletions, and the vault README trim to its Files-to-modify list. - Adds a Companion documents section linking to the new plan and the upstream-issues drafts. https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa
6 tasks
This was referenced May 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Captures the proposed simplification: drop the memory service, the
OpenViking addon, and varlock; fold the scheduler into the assistant
container; install akm in guardian/assistant/admin and share the stash
via a host bind-mount. Each capability gap is mapped to a scheduled
automation or an assistant OpenCode plugin tool.
https://claude.ai/code/session_01VEJYgDR6uqCHz8NBoVufqa