Skip to content

Instantly share code, notes, and snippets.

@jfarcand

jfarcand/atmosphere-personal-agent-strategy-v0.3.md Secret

Created April 14, 2026 18:54
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jfarcand/437ebe93e802eedf59f88e23d80481b9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jfarcand/437ebe93e802eedf59f88e23d80481b9 to your computer and use it in GitHub Desktop.
Download ZIP
Atmosphere — Personal Agent Platform Strategy v0.3 (execution-ready, private, supersedes v0.2)
Raw
atmosphere-personal-agent-strategy-v0.3.md

Atmosphere — Personal Agent Platform Strategy (v0.3)

Working draft. Secret gist. Iterated with ChefFamille.

Date: 2026-04-14 Status: v0.3 — all design questions resolved, timeline corrected to reality (hours, not months), architecture bet de-risked via reflection-based federation. Ready to execute. Predecessors: v0.1 · v0.2

Thesis (unchanged)

Atmosphere is the Java platform layer for personal agents. Pick any of the seven runtimes (Spring AI, LangChain4j, Google ADK, Koog, Semantic Kernel, Embabel, Built-in), write a skill file, inherit memory, identity, multi-channel continuity, auditable permissions, MCP / A2A / AG-UI endpoints, and durable streaming.

You don't pick Atmosphere instead of your framework. You pick Atmosphere on top of it.

Decisions locked in v0.3

# Question v0.3 decision
Memory trigger Auto-memory strategy Configurable via pluggable AutoMemoryStrategy SPI — built-ins: EveryTurn, EveryNTurns, LlmDecided, Hybrid. User picks in skill file or .agent/atmosphere/memory.yaml.
Memory storage Greenfield vs federation Hybrid — Atmosphere owns facts / working memory / hierarchical rules (runtimes have no concept of these); conversation history is read from the runtime's own storage via reflection-discovered accessors (javap -p approach). No duplication.
OpenClaw Adopt vs extend vs invent Follow OpenClaw fully. They're leading. We're followers here. Atmosphere extensions live additively in .agent/atmosphere/. If OpenClaw evolves, we follow. Better OpenClaw than inventing a new Jakarta-scale spec.
Flagship default runtime Spring AI vs Built-in Spring AI, one-line flag to switch to any of the other six.
MCP trust model Single vs pluggable Pluggable McpTrustProvider SPI — built-ins: AtmosphereEncrypted (default for local dev), OsKeychain, OAuthDelegated. User picks per MCP server in .agent/atmosphere/mcp.yaml.
Contract test latency Full matrix vs sample Representative runtime (Built-in) on PR CI, full seven-runtime matrix on main + nightly.
Architecture bet Can memory live above the runtime? Yes, via reflection-based federation. Use javap -p to discover each runtime's internal message-history accessors, read directly, never duplicate. Validates next — Action 1 below.
Timeline Weeks per theme Hours per theme. Full six-theme plan: ~8 hours total, one focused session. No monthly roadmap, no stealth window — we just ship.

What to build — six themes, hour estimates

Theme 1 — PersonalMemory SPI + reflection-federated conversation history (~2h)

Scope:

  • New PersonalMemory SPI with four query types: conversation(userId, agentId, sessionId), facts(userId, agentId), workingMemory(sessionId), rules(userId, agentId, context).
  • Conversation history federation: RuntimeConversationAdapter SPI with one implementation per runtime. Each adapter uses reflection (discovered via javap -p) to read the runtime's internal message history. No storage duplication.
  • Facts / working memory / rules — greenfield storage. SQLite + Redis backends. Atmosphere-owned.
  • Auto-memory — AutoMemoryStrategy SPI, built-ins listed above.
  • Inspection — admin control plane endpoints: GET / PUT / DELETE on /atmosphere/admin/agents/{agent}/memory/{userId}.
  • Retention policies in skill file or .agent/atmosphere/memory.yaml.
  • Contract test across all seven runtimes.

Old SPIs deprecated (no backward-compat shims): LongTermMemory, PersistentConversationMemory, SemanticRecallInterceptor, EmbeddingRuntime. Useful parts absorbed, rest removed.

Theme 2 — OpenClaw manifest loader + CLI (~1h)

Scope:

  • Read the OpenClaw spec from their canonical repo (Action 2 below, read-only, prerequisite).
  • OpenClawLoader parses .agent/identity.yaml, rules.yaml, memory/, tools/, .agentignore.
  • AtmosphereExtensionLoader parses .agent/atmosphere/channels.yaml, mcp.yaml, runtime.yaml, skills.yaml, permissions.yaml, memory.yaml.
  • CLI: atmosphere agent import ./.agent, export, validate.
  • Round-trip test: export from Spring AI, import on LangChain4j, contract-test identical behavior.

Theme 3 — Multi-agent personal assistant flagship (~2h)

Scope:

  • samples/personal-assistant/ — net-new sample module.
  • Primary agent (user-facing) + scheduler + research + drafter crew via @Coordinator / AgentFleet.
  • Default runtime: Spring AI. Flag: --runtime=built-in|spring-ai|langchain4j|adk|koog|sk|embabel.
  • Ships as an OpenClaw .agent/ directory under samples/personal-assistant/.agent/ so users can copy it as a starting template.
  • Integrates Theme 1 (memory), Theme 2 (manifest) from day one.
  • Grows in Theme 3 sub-phases: base crew → multi-channel continuity → Theme 4 permissions → Theme 5 MCP → Theme 6 skill polish.
  • The sample IS the docs. Every future demo, blog post, recruiting pitch points here.

Theme 4 — Session permission modes + per-user audit log (~1h)

Scope:

  • PermissionMode enum (DEFAULT, PLAN, ACCEPT_EDITS, BYPASS, DENY_ALL) on DurableSession. Layered over existing per-tool @RequiresApproval.
  • GET /atmosphere/admin/agents/{agent}/audit/{userId} — derived from CoordinationJournal + tool execution history.
  • Plan mode: agent generates plan, user approves before execution.

Theme 5 — Per-user MCP personal servers with pluggable trust (~1h)

Scope:

  • Per-user MCP client configuration in .agent/atmosphere/mcp.yaml.
  • McpTrustProvider SPI — AtmosphereEncrypted, OsKeychain, OAuthDelegated built-ins.
  • Admin endpoints for install / uninstall / authorize.
  • Tool invocation consults per-user MCP config at call time.

Theme 6 — Skill polish for Claude Code parity (~1h)

Scope:

  • $ARGUMENTS and {{var}} substitution in SkillFileParser.
  • Path / context / channel scoping.
  • Per-user overrides via .agent/atmosphere/skills.yaml.
  • atmosphere skill inspect CLI.

Sequencing — one focused session

Not months. Not weeks. Hours.

  1. Action 1 — architectural bet validation (~30 min): javap -p across the seven runtimes' message history classes. Confirm reflection-based federation is viable. If a runtime blocks it, note the mitigation and move on.
  2. Action 2 — OpenClaw spec read (~15 min): fetch their canonical repo, read the actual spec files. Lock Theme 2 layout against reality.
  3. Action 3 — Atmosphere memory audit (~30 min): map existing LongTermMemory / PersistentConversationMemory / SemanticRecallInterceptor / EmbeddingRuntime / ConversationPersistence / DurableSession / CheckpointStore to what Theme 1 absorbs vs deprecates.
  4. Action 4 — admin control plane audit (~15 min): map existing admin endpoints, routing, UI rendering path.
  5. Action 5 — credential handling audit (~15 min): existing secret storage (if any) for Theme 5 trust providers.

Actions 1-5 are read-only, ~90-120 min total. Then:

  1. Theme 1 — 2h
  2. Theme 2 — 1h
  3. Theme 3 — 2h
  4. Theme 4 — 1h
  5. Theme 5 — 1h
  6. Theme 6 — 1h

Total: ~10 hours including audits, closer to 8 hours for the themes alone. One long focused session, or two shorter ones.

Under the radar until the flagship sample runs end-to-end. Quiet tease after, not before.

Non-goals (unchanged)

  • No graph workflow DSL (LangGraph owns the category; our runtimes have their own).
  • No voice / realtime pipeline.
  • No code execution sandbox (tool concern, not platform).
  • No new LLM client abstraction (our clients are the seven runtimes).
  • No Python / TS feature-parity chasing.
  • No backward-compatibility shims for deprecated memory SPIs.

Success measure — six yes/no questions

  1. Build a personal agent on Spring AI, export as OpenClaw .agent/, import on LangChain4j, memory + identity preserved?
  2. User sees what agent remembers and edits it via admin control plane?
  3. Start conversation in Slack, pick up on web, agent doesn't forget?
  4. User brings own MCP tools without touching agent code?
  5. Audit per-user agent actions via admin control plane?
  6. Switch Spring AI → ADK → Koog with zero personal-agent code changes?

All six yes → shape found. Contract tests enforce each in CI.

Key insight from v0.3 — the reflection-federated memory bet

The v0.2 architectural worry was: "if Spring AI / LangChain4j own message history internally, Atmosphere can't own memory above them without duplicating."

ChefFamille's answer: don't duplicate, reference. javap -p each runtime's chat client / agent service / session class. Find the accessor (public, package-private, or private-with-reflection) that exposes the internal message list. Write a thin RuntimeConversationAdapter per runtime that reads directly from the runtime's own storage. Atmosphere never duplicates conversation history — it federates reads across runtime-native storage.

For facts / working memory / hierarchical rules, no runtime has these concepts. Atmosphere owns them cleanly in the new PersonalMemory storage.

This is a better architecture than the v0.2 "memory above the runtime" bet. Memory lives alongside the runtime, not above it. The runtime keeps conversation history where it naturally lives; Atmosphere adds the things runtimes don't think about (semantic recall, retention, inspection, portability).

Validating this bet is Action 1 below.

Status log

  • 2026-04-14 — v0.1 (gist) — thesis locked, six themes sketched, open questions.
  • 2026-04-14 — v0.2 (gist) — schema / manifest / pace / flagship / UI / contract scope resolved. Raised architectural bet about memory above the runtime.
  • 2026-04-14 — v0.3 (this gist) — all remaining questions resolved. Memory strategy pluggable, trust model pluggable, OpenClaw adopted fully, flagship on Spring AI, timeline corrected to hours. Reflection-federated memory architecture replaces "memory above the runtime". Execution begins now.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment