Atmosphere — Personal Agent Platform Strategy (v0.2)

Working draft. Secret gist. Not public. Iterated in conversation with ChefFamille.

Date: 2026-04-14 Status: v0.2 — decisions locked on memory / manifest / sequencing / flagship / admin / contract scope. Ready to begin Theme 1 scope audit. Previous: v0.1 — initial draft with the same thesis and theme list. v0.2 supersedes; v0.1 is kept as a snapshot.

Thesis (unchanged from v0.1)

Atmosphere is the Java platform layer for personal agents. You pick your framework (Spring AI, LangChain4j, Google ADK, Koog, Semantic Kernel, Embabel, or the Built-in runtime), write a skill file, and inherit memory, identity, multi-channel continuity, auditable permissions, MCP / A2A / AG-UI endpoints, and durable streaming — regardless of which runtime you picked.

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

If a feature only helps one runtime, runtime code owns it. If a feature should help all seven equally, Atmosphere owns it.

What "personal agent" means here (unchanged)

Two definitions, both in scope:

Long-lived, one user, remembers you — the Claude Code / ChatGPT memory model.
User-owned, host-portable — the OpenClaw / gitagent model.

Features that serve both are prioritized.

What to learn from — and explicitly skip (unchanged from v0.1)

Study: Claude Code Agent SDK · OpenAI Agents SDK (Python) · Anthropic memory tool + ChatGPT memory · OpenClaw / gitagent · LangGraph.

Skip: CrewAI · Smolagents · Vercel AI SDK · the seven hosted runtimes as references (we host them; we learn from them via contract tests).

Decisions locked in v0.2

These were the open questions at the end of v0.1. ChefFamille's calls:

Question	Decision	Rationale
Memory schema	Greenfield `PersonalMemory` SPI, not federation over existing pieces	No backward-compat constraint. Ship the best design. Existing `LongTermMemory` / `PersistentConversationMemory` / `SemanticRecallInterceptor` get deprecated and gradually removed.
Manifest format	Adopt OpenClaw as canonical, extend with Atmosphere	Instant compatibility with the personal-agent community that already exists. We join their ecosystem instead of forking it. Atmosphere extensions live in additive files, not modifications to OpenClaw's core format.
Pace	Implement → sample → quiet tease at month 3, noise later	3,750 stars, +1/day organic without announcements. The audience is already arriving. Feedback loop at month 3 via a single blog post + targeted community outreach, no launch. Full public narrative deferred until all six themes hold together.
Flagship sample	Net-new, multi-agent personal assistant	Theme 3 needs a purpose-built sample to prove the thesis. Multi-agent angle exercises `@Coordinator` / `AgentFleet` alongside personal-agent features — one sample proves both dimensions of the platform instead of two samples each proving one.
Memory inspection UI	Part of the existing admin control plane	`AgentController` + the existing admin REST endpoints are already the inspection surface. Add memory + audit routes there, let the existing admin UI render them. No new frontend stack.
Contract test scope	All seven runtimes, no trailing second-class citizens	Runtime-portability is the pitch. If Koog can't pass Theme 1's conformance test, we find out now. No "Theme 1 incoming" badges. Feature is done when seven passes are green in CI.

What to build — six themes (refined with v0.2 decisions)

Theme 1 — Runtime-agnostic persistent personal memory (flagship capability)

Design principle: memory lives in the Atmosphere platform layer, above the runtime. Runtimes emit and consume message chunks; Atmosphere owns the persistence, the semantic layer, the retention policy, and the inspection surface. This is how all seven runtimes pass the contract test trivially — because the memory layer is implemented once, in Atmosphere, not seven times in each runtime.

New SPI: PersonalMemory — a single interface covering:

Conversation history (per user × agent × session)
Semantic facts ("ChefFamille prefers bun over npm for RN projects")
Working memory (transient, this-session scratch space)
Hierarchical rules (system → user → project → path-scoped, Claude Code CLAUDE.md style)

Not a facade over existing SPIs. A clean greenfield design with a new schema. Existing LongTermMemory, PersistentConversationMemory, SemanticRecallInterceptor, EmbeddingRuntime are re-examined: the useful parts fold into PersonalMemory, the rest gets deprecated.

Backends: SQLite and Redis from day one. Postgres optional if the schema design naturally supports it. Plug into the existing durable-sessions-sqlite / durable-sessions-redis modules or create new ones — the module layout is part of the scope audit.

Auto-memory: agent writes memory during conversation, Claude Code style. Open question below on trigger semantics (every turn / every N turns / LLM-decided).

Inspection surface (via the admin control plane — decision locked):

GET /atmosphere/admin/agents/{agent}/memory/{userId} — redacted, human-readable view of everything the agent remembers about this user.
DELETE /atmosphere/admin/agents/{agent}/memory/{userId}/{entryId} — user-initiated entry removal.
PUT /atmosphere/admin/agents/{agent}/memory/{userId}/{entryId} — user-initiated entry edit.
GET /atmosphere/admin/agents/{agent}/memory/{userId}/retention — current retention policy for this user.
Existing admin UI renders these — no new frontend stack.

Retention policies declared in the skill file and enforced by the memory layer. TTL, max-entries, redaction flags.

Contract test — runs against all seven runtimes in CI:

Start agent on runtime X.
Send message that triggers auto-memory ("I prefer dark mode").
Restart agent.
Send new message ("what do I prefer for themes").
Assert the response references the stored fact.
Delete the fact via admin endpoint.
Send the same message again.
Assert the response no longer references it.

Seven green runs gates the theme as complete.

Theme 2 — Portable personal agent manifest (OpenClaw + Atmosphere extensions)

Canonical format: OpenClaw's .agent/ directory layout is adopted as-is. Reading an OpenClaw agent into Atmosphere Just Works. No conversion, no translation.

.agent/identity.yaml — OpenClaw canonical
.agent/rules.yaml — OpenClaw canonical
.agent/memory/ — OpenClaw canonical (Atmosphere maps this into PersonalMemory hierarchical rules at load time)
.agent/tools/ — OpenClaw canonical
.agent/.agentignore — OpenClaw canonical

Atmosphere extensions — additive files in a namespaced subdirectory, never modifications to OpenClaw's core format:

.agent/atmosphere/channels.yaml — Slack / Telegram / Discord / WhatsApp / Messenger bindings, channel-level permission modes
.agent/atmosphere/mcp.yaml — per-user MCP personal server configuration (Theme 5 lives here)
.agent/atmosphere/runtime.yaml — which of the seven runtimes to prefer, fallback chain, model routing strategy
.agent/atmosphere/skills.yaml — skill overrides on top of the curated registry (Theme 6 lives here)
.agent/atmosphere/permissions.yaml — session permission modes (Theme 4 lives here)

The manifesto: an OpenClaw agent with zero Atmosphere extensions runs on Atmosphere as a default-configured personal agent. An OpenClaw agent with Atmosphere extensions gets runtime-portability, multi-channel continuity, MCP personal servers, and the rest — without changing anything in the OpenClaw files.

Loader + CLI:

atmosphere agent import ./.agent — parse, validate, register the agent.
atmosphere agent export ./my-agent — export a running agent's full state (identity + memory + rules + tools + permissions) as a portable .agent/ directory.
atmosphere agent validate ./.agent — lint the manifest, report missing or misconfigured files.
Round-trip test: export from Spring AI, import on LangChain4j, contract-test asserts identical behavior.

Prerequisite: we need to read the current OpenClaw spec before locking Theme 2's scope. The v2-gist description was unreliable — we should fetch their canonical docs ourselves. Action item at the bottom.

Theme 3 — Multi-agent personal assistant flagship sample

Why net-new, why multi-agent: this sample is the proof point for the entire thesis. Reusing dentist-agent or expo-classroom means retrofitting a narrower story. A purpose-built personal assistant gives us the clean slate to demonstrate every theme as it lands, and a multi-agent composition exercises @Coordinator / AgentFleet as a first-class part of the personal-agent story — not a separate concern.

The sample (working name — TBD):

A personal productivity assistant composed as a small fleet:

Primary agent — the user-facing conversation, owns the persona and memory.
Scheduler agent — calendar integration via MCP personal server.
Research agent — web search, document retrieval.
Drafter agent — writes emails, docs, messages on behalf of the user.

The user talks to one agent ("my assistant"). Behind the scenes the primary agent fans out to specialized crew members via AgentFleet, each with its own tool access and permissions. The user never sees the fleet — but the audit log (Theme 4) shows exactly which crew member did what.

What it demonstrates as each theme lands:

Month 1, Theme 1 + 2 land → the sample gains persistent memory across restarts and ships as an OpenClaw .agent/ directory. The blog post is "your personal assistant travels with you across runtimes".
Month 2, Theme 3 sample itself → the sample gains multi-channel continuity. User starts in Slack, continues on web, finishes on mobile. One assistant, one memory, three channels.
Month 2, Theme 4 → the sample gains plan mode and a per-user audit endpoint. "Show me what my assistant did today" works.
Month 3, Theme 5 → the sample gains per-user MCP personal servers. Users install their own GitHub / Gmail / filesystem tools.
Month 3, Theme 6 → skill polish makes the assistant's persona configurable per-user via argument substitution.

The sample itself becomes the docs. Every future demo, blog post, recruiting pitch points at this one running assistant.

Cost: ~2 weeks of engineering for the base fleet, then ~1-2 days per theme to integrate. The cost is real but pays back every time we need to show Atmosphere to someone.

Theme 4 — Session permission modes + per-user audit log (unchanged from v0.1)

PermissionMode enum (DEFAULT, PLAN, ACCEPT_EDITS, BYPASS, DENY_ALL) on the durable session, layered over per-tool @RequiresApproval. Per-user audit endpoint served via admin control plane (decision 5 locked — admin is the inspection surface for everything user-scoped, not just memory).

GET /atmosphere/admin/agents/{agent}/audit/{userId} — what has this agent done on behalf of this user.
Derived from CoordinationJournal + tool execution history — the data exists, the endpoint doesn't.
Plan mode generates a plan, user approves before execution. Claude Code parity on the highest-leverage permission mode.

Theme 5 — Per-user MCP personal servers (unchanged from v0.1)

Per-user MCP client configuration stored in .agent/atmosphere/mcp.yaml (Theme 2 decision locks the location). User brings their own tools with their own credentials. Tools consult per-user MCP configuration at runtime. Admin endpoints (decision 5) expose install / uninstall / authorize flows.

Single hardest piece: the trust model for user-supplied MCP tokens. Still an open question, see below.

Theme 6 — Skill polish for Claude Code parity (unchanged from v0.1)

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

Sequencing — 90 days

Month 1: Themes 1 + 2. Memory SPI, greenfield schema, OpenClaw adoption, manifest loader, CLI import / export / validate, admin memory endpoints, contract test across all seven runtimes.
Month 2: Themes 3 + 4. Net-new multi-agent flagship sample shipped. Continuity across channels. Permission modes. Audit endpoint. Sample integrates Theme 1 + 2 output.
Month 3: Themes 5 + 6. Per-user MCP servers. Skill polish. Sample grows to demonstrate both. Quiet tease at end of month 3: one blog post on async-io.org, targeted outreach to four or five Java-AI community figures, no roadmap commitments, invite private feedback.

The gated deliverable at the end of each month is the flagship sample demonstrably working with that month's features, not a README or a changelog entry. If the sample doesn't run, the month isn't done.

Non-goals (the explicit no's that protect focus)

No graph workflow DSL. LangGraph owns the category; our seven runtimes have their own. We have @Coordinator / AgentFleet.
No voice / realtime pipeline. Revisit after the base holds.
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 on anything that doesn't pass the runtime-agnostic filter.
No backward-compatibility shims for the existing memory SPIs (decision locked — we ship the best design, existing pieces get deprecated and removed cleanly).

Success measure — six yes/no questions, six months out

Can I build a personal agent on Spring AI, export it as an OpenClaw .agent/ directory, import it on LangChain4j, and it keeps memory + identity?
Can my user see what their agent remembers about them and edit it via the admin control plane?
Can my user start a conversation in Slack, pick it up on web, and the agent doesn't forget?
Can my user bring their own MCP tools (GitHub, Gmail, filesystem) without touching my agent code?
Can I audit everything an agent has done on behalf of a specific user via the admin control plane?
Does switching from Spring AI to ADK to Koog require zero personal-agent code changes?

All six yes → Atmosphere has found its shape. Any no → we know what to build next.

Contract tests enforce each answer in CI. Same philosophy as AbstractAgentRuntimeContractTest.expectedCapabilities(). All seven runtimes pass or the feature isn't done.

Key success factors while under the radar

3,750 stars, +1/day organic. The audience is arriving without announcements. Don't disturb the organic curve with premature noise — build the things that make those arriving users stay.
Contract-tested guarantees, no superlatives. If we say "runs on all seven runtimes", we prove it in CI per-feature. The v2-gist failure mode (unverifiable claims) is banned at the document level.
Flagship sample, not feature lists. The multi-agent personal assistant is the only demo that matters. Every theme ships integrated into that one sample.
One post per month at most, and only after month 3. Quality narrative compounds; noise doesn't. Until month 3, no public content.
Refuse the framework war. "Atmosphere hosts your LangChain4j / Spring AI agents" is the answer to every comparison question. We are the platform, not the competitor.
Own the Java narrative. Virtual threads, MCP / A2A / AG-UI convergence, fifteen years of async / real-time heritage. The enterprise Java crowd is under-served on personal agents and that's our audience.
Recruit the Claude-Code-pilled, not the LangGraph-pilled. The users who want "Claude Code for my Spring Boot shop" are our audience. The ones who want a workflow DSL in Java aren't — send them to Temporal.

Open questions (v0.2 cohort)

Resolved in v0.2 (schema / manifest / pace / flagship / UI / contract scope) are removed. These are the questions that surfaced or remain after locking the above.

Memory layer design

Auto-memory trigger semantics: every turn / every N turns / LLM-decided via tool call / hybrid. Each has different failure modes. Claude Code uses LLM-decided via the memory tool; ChatGPT memory uses a hybrid of LLM-decided + summary compaction. My lean: LLM-decided via a built-in remember tool the agent can call, plus a background compactor that runs every session-end. Needs prototyping.
PersonalMemory SPI granularity: one interface with four query methods (conversation / facts / working / rules) or four separate SPIs that share a backend? Single interface is simpler for consumers, four SPIs is cleaner for pluggable backends. Probably single interface with typed query records.
Semantic recall integration: embed-on-write or embed-on-read? Embed-on-write is faster at query time but wastes compute on memory that's never recalled. Embed-on-read is cheaper but adds latency to every recall. ChatGPT memory does embed-on-write; Claude Code does embed-on-read (file read). Lean: embed-on-write for facts, embed-on-read for conversation history.
Hierarchical rules storage: as structured rows in personal_memory or as flat text files loaded at session start (Claude Code CLAUDE.md style)? Files are more portable (they sit in .agent/memory/ which lines up with OpenClaw Theme 2). Lean: files on disk, indexed in personal_memory for query, canonical source is the file.

Manifest / OpenClaw adoption

What's actually in the current OpenClaw spec — the v2 gist description was unreliable, we need to read their repo directly before locking Theme 2. Action: fetch the OpenClaw / gitagent repo and read the canonical files. This is a blocker for Theme 2 scope.
OpenClaw version pinning: do we pin to a specific spec version (say, OpenClaw 1.0) or track their main branch? Pinning is safer; tracking main keeps us in lockstep with the community. Lean: pin to a specific tagged version, document compatibility, upgrade deliberately.
Round-trip semantics: if an OpenClaw agent has features Atmosphere doesn't support (or vice versa), what's the round-trip behavior? Lossy with warning? Validation error? Lean: lossy with warnings logged, plus a strict-mode flag for CI.
Whose memory format wins for the .agent/memory/ directory: OpenClaw's (if they have one) or Atmosphere's? They should be the same. Either we adopt theirs or we contribute ours upstream. Bias toward contributing upstream so we don't fork the ecosystem.

Multi-agent flagship sample

Sample name — "personal assistant" is generic. "atmo" / "jarvis" / "copilot" are taken or too cute. Lean: something that says "Java personal agent" without overclaiming. Ideas welcome.
Crew composition — primary + scheduler + research + drafter is my sketch. Should there be a "memory agent" as a dedicated fleet member, or is memory owned by the primary? Architecturally memory is cross-cutting, shouldn't be its own agent. Lean: memory is platform-level, not crew-level.
Which runtime ships as default — the sample has to pick one default runtime. Spring AI is the safe choice (enterprise Java audience) but Built-in is the zero-dep demo story. Lean: default to Spring AI for enterprise resonance, provide a one-line flag to switch to any of the other six to prove runtime-portability.
Do we ship sample fleet members as separate agent modules or one monolith with four @Agent classes? Separate modules is cleaner for demonstrating fleet composition across module boundaries. Lean: separate modules.

Theme 5 — MCP personal server trust model

Who verifies user-supplied MCP tokens: Atmosphere holds them encrypted, the user holds them in OS keychain, or OAuth-style delegation where Atmosphere never sees the raw token? Delegation is safest but requires every MCP server to support an OAuth flow (most don't today). Lean: support all three, with OS keychain as the default for local dev and delegation when the MCP server supports it.
Per-user secret storage — new module or reuse existing credential store? Atmosphere may not have a credential store today. Action: audit the repo for existing secret-handling before deciding.
Token rotation / revocation — if a user revokes a GitHub token externally, how does the per-user MCP config handle the resulting 401? Auto-detect and flag in admin UI, re-prompt user to re-authorize. Non-trivial UX work.

Contract tests across all seven runtimes

What if a runtime architecturally can't pass? For example, a runtime whose agent loop doesn't expose hook points for memory writes. Decision 6 says no second-class citizens — but a runtime that's structurally incapable may need upstream changes. Lean: if the Atmosphere platform layer handles memory above the runtime (the architectural bet of Theme 1), no runtime should be structurally incapable. But we should validate this assumption in the Theme 1 scope audit before committing.
Test latency budget — running seven full conformance tests for every PR could add significant CI time. Lean: run full seven-runtime matrix on main + release branches, run a single representative runtime (Built-in) on PR CI, let nightly catch runtime-specific regressions.

Immediate next actions

Before Theme 1 work begins:

Fetch OpenClaw / gitagent canonical spec from their repo. Read the actual files, not the v2-gist description. Lock Theme 2's file layout against reality.
Audit existing Atmosphere memory-adjacent code: LongTermMemory, PersistentConversationMemory, SemanticRecallInterceptor, EmbeddingRuntime, ConversationPersistence, DurableSession, CheckpointStore. Map what each one does today, what the greenfield PersonalMemory needs to absorb, what gets deprecated. This is the scope audit for Theme 1.
Audit the admin control plane: the 25+ REST endpoints, how they're routed (AgentController, CoordinatorController, etc.), how the existing admin UI consumes them, which module owns the frontend. This is the scope audit for the inspection surface.
Audit existing credential / secret handling (if any) in the repo. Theme 5 trust model depends on this.
Validate the "memory above the runtime" architectural bet — read AbstractAgentRuntime and the hook points the Built-in, Spring AI, and LangChain4j runtimes expose today. Confirm that memory can live in the platform layer without runtime cooperation beyond emitting message events.

All five actions are read-only. No code written until they're done and we've discussed the findings.

Status log

2026-04-14 — v0.1 (gist) — thesis locked, six themes sketched, 90-day sequencing, open questions on schema / manifest / pace / flagship / UI / contract scope.
2026-04-14 — v0.2 (this gist) — all six v0.1 open questions resolved. Greenfield PersonalMemory, OpenClaw adoption + extension, quiet tease at month 3, net-new multi-agent flagship, admin control plane for inspection, all-seven-runtimes contract tests. Next: execute the five immediate actions above and reconvene for Theme 1 scope lock.

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

Select an option

No results found