AI OS Rework — Synthesis

Created 2026-05-13

Tags planningai-osknowledge-basevault-development

Research synthesis for a potential restructure of the Baseworks KB to align with an agentic operating system architecture. This document grows as sources are added. No implementation decisions until the source review is complete.

Status: Source review complete — 5 of 5 sources reviewed. Ready for implementation discussion.

Sources

#	Source	Date	Angle	Doc
1	Nick Milo — “The 3-File AI System That Works With ANY MODEL”	2026-05-09	Personal knowledge management; Obsidian-native; tool-agnostic portability	nick-milo-ai-os-planning
2	Simon Scrapes — “Creating Your Own Agentic OS is Easy”	2026-05-13	Business workflow OS; Claude Code-native; autonomous scheduled execution	simon-scrapes-agentic-os
3	Chase AI — “Claude Code Agentic OS = UNSTOPPABLE”	2026-05-13	Org-chart mental model; Obsidian memory; non-technical team access; local vs remote automation	chase-ai-agentic-os
4	IBM Technology — “Why AI Agents Need an Operating System”	2026-05-13	Foundational vocabulary; three-layer architecture; six kernel components defined (scheduler, memory, tools, identity, observability, guardrails)	ibm-agent-os-framework
5	The AI Daily Brief — “How To Build a Personal Agentic Operating System”	2026-05-13	Practitioner 7-layer model; explicit portability design; Verification + Connections layers unique to this source; AI interview methodology	aidb-agent-os

Cross-Source Matrix

Dimension	Nick Milo	Simon Scrapes	Chase AI	Newgard Gaspar	Baseworks Relevance
Identity (“who am I”)	`me.md` — portable identity: philosophy, values, working preferences. At vault root.	`user.md` (operator) + `SOUL.md` (agent persona). Two distinct files.	No explicit identity file. System is operator-facing through the org chart structure, not through a personal document.	Layer 1: tool-agnostic identity file. Named across all tools (CLAUDE.md, agents.md, soul, etc.). “Written once. Enforced forever.”	High. Patrick and Asia need distinct identity files. Two `me-[name].md` files is the right shape.
Navigation / context map	`vault-map.md` — describes folder structure, note conventions, cross-ideaverse links.	`brand_context/` folder — voice profile, ICP, positioning. Referenced by skills at runtime.	Org chart of domains (Memory / Productivity / Research / Content / Custom) — a mental model for the operator, not a file for AI navigation.	Layer 2: Context Library — 3-5 focused single-page files. Stakeholders, strategy/priorities, operating principles. “Context curation is a practice, not a project.”	High. vault-map.md for AI navigation (Milo) + domain map for operator comprehension (Chase) + situational context files (Gaspar) are complementary layers.
Skill design	Plain markdown in `AIOS/Skills/`. Triggers and descriptions. Portable to any tool.	Progressive Disclosure — 3-level loading: YAML frontmatter → SKILL.md body → linked files. Skills explicitly reference brand_context.	Skills map to daily workflow tasks. Use skill creator for consistent format. Organized by domain branch. Infinitely editable.	Layer 3: TRIGGER → PROCESS → OUTPUT (identical structure to Simon). MVP first, patch over weeks. “Every knowledge worker has 20-30 of these patterns.”	High. Progressive Disclosure (Simon) + domain organization (Chase) + portable markdown (Milo) + MVP discipline (Gaspar) is the synthesis target.
Memory / session recall	`AIOS/History/` — date-stamped AI interaction logs.	6-level framework: CLAUDE.md → session start hook → semantic search → verbatim recall → knowledge base → cross-tool DB. Levels 1+2+3 as the 80/20.	Obsidian vault as memory. `/raw` → `/wiki` → `/projects` flow. `claude/memory` subfolder for auto-memory writes. No complex RAG needed.	Layer 4: Deliberate memory over passive accumulation. Understand the tool’s memory limits first. Structured memory files. “Memory is what makes every other layer stick across sessions.”	High. The raw/wiki/projects flow (Chase) + AIOS/History log (Milo) + session start hook (Simon) + deliberate structured memory files (Gaspar) stack together.
Portability across tools	Explicitly tool-agnostic. `CLAUDE.md` = one-liner redirect; all content in tool-neutral markdown files.	Partially portable — skills are markdown but hooks, context inheritance, and Channels are Claude Code-specific.	Tightly Claude Code-specific — the most tool-locked of the three sources. Dashboard, routines, and headless mode are all Claude Code features.	Explicitly the primary design constraint. The OS is tool-agnostic content; each tool has a thin entry-point file. Most portable of all five sources.	Medium. Content layer must stay tool-agnostic (Milo, Gaspar). Claude Code-specific features (hooks, inheritance) live in the execution layer only, not in the content files.
Obsidian integration	Deep. Built for Obsidian: ACE structure, MOCs, graph view, wikilinks.	None explicit. Generic folder system. No Obsidian-specific features referenced.	Explicit Obsidian use for memory. Output from skills is reflected in the vault. Vault Cleanup is a built-in skill. Dashboard links directly to vault.	Not addressed. Generic folder system assumed.	Chase + Milo together give the fullest Obsidian-specific picture.
Multi-operator / team	Multi-ideaverse model — personal, team, family vaults with translation layer between them.	Multi-client folder inheritance — shared root + per-client context isolation.	Explicitly frames for team use: “driven by anyone on your team.” Dashboard gives non-technical members access without a terminal.	Personal OS framing. Enterprise rollout handled separately by Enterprise Claw.	High. Patrick + Asia share the vault. Separate identity files + clear session attribution + (optionally) a simplified skill interface for non-CLI workflows covers this.
Scheduled / autonomous	Not covered.	Explicit: cron, skill systems, Claude Code Channels.	Local vs remote automation distinction. Claude Desktop Routines. VPS / Mac mini for always-on local execution.	Layer 7 (Automations): draft-first, manual-tested-first, always-logged. Automations are earned — they sit above all other layers.	The local/remote split (Chase) + Channels (Simon) + draft-first rule (Gaspar) together cover the full automation picture. VPS already in place.
Implementation complexity	Low to start — `me.md` + `vault-map.md` takes hours, delivers value immediately.	Medium — identity files + brand context + memory hook + skill refactor + output folder.	Medium — org chart planning + skill domain mapping + Obsidian structure + optional dashboard.	Low to start — bottom-to-top: identity first, then context, then skills. “70% first version, patch as you use it.”	Stage it. The content layer (identity + vault-map) first; then skills refactor; then memory hook + session log; then automation.
OS maintenance / decay prevention	Not addressed explicitly.	Not addressed explicitly.	Not addressed explicitly.	Layer 6 (Verification): periodic OS audit. Without it: ~8 weeks to stale. “With it your OS compounds even further and forever.”	High. Quarterly audit of skills, context files, and identity against current vault conventions is a new practice to add.
Connections security	Not addressed.	Not addressed.	Not addressed.	Layer 5 (Connections): read-only-first rule. Least privilege. The risk scales with capability. Write access only after trust is established.	High. All Claude Code integrations with external systems (WP-CLI, email, calendar) should follow the read-only-first model. The implicit “ask Patrick first” norm should be made explicit in the OS design.

What All Sources Agree On

Universal principles — present across all five sources:

Identity files are the foundation. Who you are and how you work must live in files you own, outside any specific tool’s config. The tool entry point (CLAUDE.md) should point to them, not contain them.
The tool entry point should be thin. CLAUDE.md = a redirect, not the document. Content belongs in files any AI can read.
Skills belong in plain markdown. Portable. Not locked to a platform or model version.
Separation of concerns. Identity / navigation / skills / memory should be distinct files, not one monolithic config.
Build incrementally. Start minimal, use it, observe what’s broken, improve. A perfect system on day one is not the goal.
Memory is mandatory. All five sources treat session recall as non-negotiable, not optional.

Where They Differ

Point of difference	Nick Milo	Simon Scrapes	Chase AI	Newgard Gaspar	IBM	Implication for Baseworks
Primary frame	Personal knowledge + thinking	Business workflow + content production	Team OS + client delivery	Personal OS designed to compound over time; earn automations layer by layer	Conceptual vocabulary for all of the above	All frames apply. The vault serves personal thinking, business production, and team collaboration.
Context injection	`CLAUDE.md` reads `me.md` — Claude chooses to follow. Explicitly thin: only a redirect.	Session start hook forces context in deterministically.	Org chart structure forces operator to maintain clarity; no explicit injection beyond CLAUDE.md.	Context Library (3-5 focused single-page files); context curation is ongoing practice, not a project. No injection mechanism specified.	Memory Manager component; no implementation guidance.	Simon’s hook approach is the most reliable for injection. Milo’s thin redirect is the most portable. Gaspar’s context curation practice ensures the files being injected stay fresh. Use all three together.
Skill portability	Explicit goal — skills run in any tool.	Partially portable — markdown skills, but Claude Code execution layer.	Not a design goal — tightly coupled to Claude Code.	Explicit primary goal — platform, model, and harness neutral. “If you write it once well, it fires forever.”	Tool Manager component; no implementation guidance.	Design skills as portable markdown (Milo, Gaspar). Claude Code features are the execution layer only — never embedded in the skill file itself.
Vault structure	ACE (Atlas / Calendar / Efforts) — specific reorganization.	Flat folder system per project/client.	Domain branches (Memory / Productivity / Research / Content / Custom).	Generic folder system assumed. No specific structure prescribed.	Not addressed.	Keep existing numbered folder system. Write a vault-map that describes it clearly. Adopt Chase’s domain-branch mental model as an overlay for skill organization — not as a folder restructure.
Tool coupling	Tool-agnostic by design.	Moderate — Claude Code features used but skills are markdown.	High — most Claude Code-specific of all practitioner sources.	Lowest coupling — explicitly designed to work across tools.	Not applicable (vocabulary source).	Content layer: tool-agnostic (Milo, Gaspar). Execution layer: Claude Code-optimized. Keep them cleanly separated.
OS maintenance / decay	Not addressed.	Not addressed.	Not addressed.	Explicit: Verification layer, ~8 weeks to stale without periodic audit.	Observability component (passive logging); no maintenance guidance.	Quarterly OS audit is a new design requirement.
Security model	Not addressed.	Not addressed.	Not addressed.	Connections layer: read-only-first rule, least privilege. “The risk scales with the capability.”	Guardrails + Governance component — only source to fully address this.	Read-only-first applies to all Baseworks external integrations. The “ask Patrick first” norm needs to become an explicit OS rule.

LLM-Agnostic Design — The Portability Requirement

“For any LLM, we need to be able to jump in at any point and work with our OS within its own protocol and structure, without affecting the way any other LLM will be interpreting the output across the structure itself.”

This is the most architecturally significant constraint for Baseworks. Among the five sources: Newgard Gaspar makes it the explicit primary design goal (“platform, model, and harness neutral”); Nick Milo frames it as “File over AI” and builds the whole system around it; Simon Scrapes is in the middle (portable skills, Claude Code-specific execution); Chase’s model largely fails this — it assumes Claude Code as the sole tool; IBM addresses it at the vocabulary level only. Gaspar and Milo together form the portability argument; Chase’s model is useful for Claude Code-specific capability but its content layer must be separated from the execution layer to preserve portability.

What LLM-agnostic design requires:

Requirement	Design decision
Content files readable by any AI	All identity, vault-map, brand-context, and skill files are plain markdown. No Claude Code-specific syntax inside them.
Session attribution	Every entry in `AIOS/History/` and every memory write includes frontmatter: `operator:`, `tool:`, `date:`. One tool’s session notes can’t be confused for another’s.
Tool entry points are thin and separate	`CLAUDE.md` (Claude Code) = redirect to me.md + vault-map.md. A future `GEMINI.md` or `SYSTEM_PROMPT.md` for another tool reads the same underlying files. Only the entry point file is tool-specific.
No tool-specific syntax in content	Hooks, context inheritance, and Channels live in `.claude/settings.json` and Claude Code config — never embedded in the markdown content files themselves.
Memory writes are attributable	`AIOS/History/2026-05-13-session-claude-patrick.md` — filename and frontmatter make it clear which tool wrote it and who operated it. Cross-tool queries can filter or weight by source.

Practical consequence: The AIOS/ folder is the interface layer. Everything inside it must be plain markdown that any reasonably capable AI can read cold and act on. The Claude Code-specific execution machinery (hooks, settings, skills directory conventions) wraps around the AIOS content but does not leak into it.

Multi-tool entry point design:

Each AI tool reads a different entry-point filename in a different location — but they all redirect to the same underlying content:

Tool	Entry-point file	Location
Claude Code	`CLAUDE.md`	Vault root (or `.claude/CLAUDE.md`)
Cursor	`agents.md`	Workspace root
GitHub Copilot	`.github/copilot-instructions.md`	Repo root
Gemini / other	`SYSTEM_PROMPT.md` or tool equivalent	Workspace root
Claude Web / Claude Desktop	Copy-paste or project instructions UI	External to vault

Every entry-point file contains the same two-step logic: (1) detect operator from machine context or ask, (2) load me-[name].md + vault-map.md. Only the filename and tool-specific syntax differ. The content they redirect to is identical across all tools.

Tool-specific folder conventions:

Each tool has its own dot-folder for tool-specific config. These are not created proactively — they are created on first use of that tool in the vault, when you’ve identified a tool-specific capability worth wrapping:

Tool	Tool-specific folder	What goes there
Claude Code	`.claude/`	`settings.json`, hooks, tool-specific skill wrappers, Channels config
Cursor	`.cursor/rules/`	Cursor-specific rules and agent configuration
OpenAI Codex	`AGENTS.md` + `.codex/` (if it exists)	Codex agent instructions; tool-specific config
Gemini CLI	`.gemini/` or `GEMINI.md`	Gemini-specific config and tool-specific rules
GitHub Copilot	`.github/copilot-instructions.md`	Copilot workspace instructions

Skills and the multi-tool context:

.claude/skills/ is where Claude Code looks for skills. Other tools have different conventions. The solution is two-layer: a tool-agnostic AIOS/Skills/ folder containing portable skill markdown files (pure TRIGGER → PROCESS → OUTPUT, readable by any AI), and tool-specific folders (.claude/, .cursor/rules/, etc.) that contain execution wrappers for their own platform capabilities. Skills that use Claude Code-specific features (hooks, Channels, context inheritance) belong in .claude/ only. Skills that are pure instruction sets belong in AIOS/Skills/ and are referenced from the tool-specific layer.

On auto-detection of new tools: There is no automatic mechanism that detects a new tool and creates its folder. This is not a problem that needs solving at the OS design level. The workflow is: (1) AIOS/Skills/ is always ready — a new tool can reference portable skills immediately by pointing its entry-point file at AIOS/Skills/; (2) a tool-specific folder (.cursor/, .codex/, etc.) only gets created when you’ve identified a capability that tool has that others don’t and you want to wrap a portable skill with it. Tools you haven’t used yet don’t need setup — they are inert until you open them in the vault directory and create their entry-point file. See Open Questions for Implementation Discussion item 11 for the skills refactor design.

Dual-Operator Session Management — Patrick + Asia

“It would require that any new session starts by understanding who’s actually starting the session.”

Patrick and Asia share the vault, have distinct roles and voices, and use different machines and tools. A session started by Patrick on his MacBook Pro is a different context from one started by Asia on her MacBook Air or via Claude Web. The OS needs to know this at session start.

The problem: Currently there is no operator identification in the session flow. CLAUDE.md doesn’t distinguish between operators. Sessions accumulate in inboxes but aren’t systematically attributed.

The full machine inventory:

Machine	Operator	Type	Notes
Patrick’s MacBook Pro	Patrick	Primary dev machine	Claude Code CLI; vault editing
Patrick’s Mac mini	Patrick	Secondary / always-on	May run scheduled tasks
Asia’s MacBook Air	Asia	Primary machine	Claude Code CLI; vault editing
Asia’s Mac mini	Asia	Secondary / always-on	May run scheduled tasks
VPS (baseworks-agents)	System / either	Server	Cron-triggered; operator declared per job

All Patrick machines → me-patrick.md. All Asia machines → me-asia.md. Machine granularity matters for session log attribution (which machine ran this, not just which operator), but not for identity file selection. The VPS is the only case where operator identity isn’t inherent to the machine.

The solution — three layers:

Layer 1: Machine-based detection (Claude Code on known machines)

The existing machine identity convention in CLAUDE.md already establishes this for Claude Code via $HOSTNAME:

Patrick’s MacBook Pro, Patrick’s Mac mini → CLAUDE.md redirects to me-patrick.md
Asia’s MacBook Air, Asia’s Mac mini → CLAUDE.md redirects to me-asia.md
VPS → CLAUDE.md redirects based on who triggers the session, or defaults to a prompt

This is the zero-friction path for CLI sessions. No action required from the operator — the machine identity is implicit.

Layer 2: Session prompt for ambiguous contexts (Claude Web, Claude Desktop, VPS, other tools)

When machine identity can’t determine the operator — or when a tool other than Claude Code is used where $HOSTNAME detection isn’t available — the entry-point file includes:

If you cannot determine from context who is running this session,
ask at the start: "Is this Patrick or Asia?" then load the
appropriate me-[name].md before proceeding.

This adds one exchange at session start but ensures no session runs with the wrong operator context.

Layer 3: Session log attribution

Every AIOS/History/ entry includes operator, tool, and machine in both filename and frontmatter:

---
operator: patrick
tool: claude-code
machine: patricks-macbook-pro
date: 2026-05-13
---

Filename convention: YYYY-MM-DD-[description]-[operator].md

What goes in me-patrick.md vs me-asia.md:

Element	`me-patrick.md`	`me-asia.md`
Role and responsibilities	Lead instructor, business direction, content creation	Teaching, curriculum support, community management
Voice and communication style	Formal and precise in professional contexts	See Asia’s voice guide
Working preferences for AI	Terse responses, no trailing summaries, no em-dashes	Separate — defer to Asia’s preferences
Pointers to shared resources	→ vault-map.md, brand-context/, skill-map.md	Same shared pointers
Machine identifiers	Patrick’s MacBook Pro, Patrick’s Mac mini	Asia’s MacBook Air, Asia’s Mac mini

Shared vs personal context:

vault-map.md — shared (the vault structure is the same for both)
brand_context/ — shared (the brand voice belongs to Baseworks, not to one person)
me-[name].md — personal (role, preferences, how AI should interact with this specific person)
AIOS/History/ — shared log, but attributed per entry

Applicability to Baseworks — Updated

Baseworks is a two-operator knowledge business with an Obsidian vault, a Claude Code-heavy workflow, and a shared brain that feeds both internal operations and kb.baseworks.com.

What we already have (stronger than a typical starting point):

Detailed voice guides — richer than Simon’s voice-profile.md starting point
.claude/skills/ with a dozen+ active skills — the skill layer exists, needs refinement not invention
CLAUDE.md at vault root — the entry point exists, needs to become a thinner redirect
VPS running Claude Code — infrastructure for scheduled/autonomous execution already in place
SQLite vault index, wikilink checker, sync pipeline — operational tooling is solid
Inbox system with operator attribution — partial session handoff already established

What’s missing:

Separate identity files per operator (me-patrick.md, me-asia.md)
A vault-map.md — AI navigation instructions currently mixed into CLAUDE.md
A session start hook — context loaded optionally, not deterministically
A structured, attributed AI session log (AIOS/History/)
Auto-memory convention — no claude/memory subfolder for Claude Code to write session notes
Explicit brand context injection in skills — skills don’t pull from voice guides as a standard first step
Domain skill map — no org-chart view of what skill domains Baseworks has (Chase’s contribution)
Structured output folder — AI outputs go wherever; no predictable retrieval path
Operator identification mechanism — no session-start detection of who is running

Provisional component map (updated with all five sources):

Component	Primary source	Baseworks location	Notes
`me-patrick.md`	Milo + Scrapes	Vault root	Role, preferences, working style, machine list, pointers to shared maps
`me-asia.md`	Milo + Scrapes	Vault root	Same structure, Asia’s context
`me-baseworks.md` (open question)	Gaspar + Patrick	Vault root	Neutral brand voice; loaded when output is attributed to Baseworks, not a person
`CLAUDE.md` (thin redirect)	Milo + Gaspar	Existing file	Slim to ~5 lines: detect machine hostname → load me-[name].md + vault-map.md
Tool entry-point files	Gaspar	Tool-specific roots	`agents.md`, `GEMINI.md`, `copilot-instructions.md` — each a redirect to same underlying files
`vault-map.md`	Milo	`AIOS/Maps/vault-map.md`	Describes existing 00–04 folder system; note creation conventions; sync pipeline notes
`brand_context/`	Scrapes	`AIOS/brand-context/`	voice-profile.md (condensed from voice guides), positioning, ICP
Domain skill map	Chase	`AIOS/Maps/skill-map.md`	Baseworks domains: Communications / Practice Platform / Educational Programs / Research / Operations
Session start hook	Scrapes	`.claude/settings.json`	Forces vault-map + active-projects context on every session
`AIOS/History/` session log	Milo + Chase	`AIOS/History/`	Filename: `YYYY-MM-DD-description-operator.md`; frontmatter: operator, tool, machine, date
`AIOS/memory/` auto-memory	Chase + Gaspar	`AIOS/memory/`	Claude Code writes session notes; deliberate memory habits (Gaspar) define what gets captured
`AIOS/Skills/` portable skills	Milo + Gaspar	`AIOS/Skills/`	Pure TRIGGER → PROCESS → OUTPUT markdown; readable by any AI tool cold
`.claude/skills/` Claude-specific	Scrapes + Chase	`.claude/skills/`	Execution wrappers using hooks, Channels, context inheritance; references AIOS/Skills/
Tool-specific folders	Gaspar	`.cursor/`, `.codex/`, `.gemini/` etc.	Created on first use; contains tool-specific execution wrappers only
Output folder	Scrapes + Chase	`AIOS/Outputs/`	Per-skill or per-project subfolders
Operator detection	Gaspar + Patrick	`CLAUDE.md` per machine + me-[name].md	Machine hostname-based for Claude Code; session prompt for other tools
OS audit practice	Gaspar	`/os-audit` skill (to build)	Quarterly: staleness check on context files, unused skills, outdated identity references
Connections permission map	Gaspar	`AIOS/Maps/connections.md` (to build)	Documents each external integration and its current permission level (read-only vs write)
Media asset pipeline	Baseworks-specific	`AIOS/Skills/process-media.md` (portable) + `.claude/skills/compress-photos/` (execution)	Portable skill describes workflow; execution requires Claude Code with b2 CLI + NAS SSH. All other tools drop assets to Desktop/tmp, hand off to Claude Code.

What Baseworks probably doesn’t need:

Full ACE folder restructure — the numbered system works; vault-map explains it
Multi-client folder inheritance — one vault, not multiple client repos
GSD build framework — for software builds, not knowledge/content work
Cross-tool memory DB (Simon levels 5–6) — Claude Code is primary; levels 1–3 suffice
Full custom dashboard build — overkill for two people; may become relevant if staff or practitioners are onboarded

Newgard Gaspar Framework — Two Unique Contributions

Source 5 (aidb-agent-os) adds two layers with no equivalent in the other four sources:

1. The Verification layer — OS decay prevention

Every other source assumes the operator maintains the system intuitively. Newgard Gaspar names the failure mode explicitly:

“Without the audit discipline, your OS has a shelf life of maybe 8 weeks before everything goes stale. And with it, your OS compounds even further and forever.”

The fix is structured: periodic retrospectives with agents, auditing which context files have gone stale, which skills are unused, which agents need updated instructions. This can be done directly from the tool — ask it what isn’t being used. The decay timeline (8 weeks) is the most concrete maintenance guideline in the entire series.

For Baseworks: A quarterly OS audit is now a design requirement, not an optional practice. The Baseworks vault already shows this pattern — skills written 3+ months ago reference outdated voice guide versions or inbox protocols. A /vault-audit skill already partially covers this; a dedicated /os-audit skill (checking identity files, context files, and skills against current vault state) is worth adding to the backlog.

2. The Connections layer — explicit security model

The read-only-first rule is the clearest security guidance in the series:

“Start with read-only access. Write access should be added after you watch the agent behave for a few weeks and you’ll have enough trust. The risk scales with the capability.”

For Baseworks: Any Claude Code integration that takes write actions on external systems (WP-CLI to live sites, email, calendar, practice.baseworks.com) should be documented with its current permission level. The informal “check with Patrick first” norm is already the human equivalent of this principle — it should be made explicit in the OS design so Asia and any future session can apply it without needing to ask.

IBM Framework — Shared Vocabulary

The IBM source (Source 4) does not add new implementation dimensions to the matrix above — it provides the architecture vocabulary that the four practitioner sources all implement without naming consistently.

The six kernel components (IBM) mapped to what the synthesis already covers:

IBM Component	What it maps to in this synthesis
Scheduler / Orchestrator	Skill chaining (Simon), domain routing + cron (Chase)
Memory Manager	Simon’s 6-level memory framework; AIOS/History/ session logs (Milo); claude/memory subfolder (Chase)
Tool Manager	Progressive Disclosure skills (Simon); domain skill branches (Chase); local vs remote execution (Chase)
Identity Manager	`me-patrick.md` / `me-asia.md`; session attribution in AIOS/History/
Observability	AIOS/History/ passive session logs; session hook logging (Simon)
Guardrails + Governance	Not addressed by any practitioner source. All four practitioner sources (Milo, Scrapes, Chase, Gaspar) assume a single trusted human operator always present. Only becomes a design concern if Baseworks moves toward fully autonomous multi-agent execution without operator oversight.

Why this matters: The guardrails + governance component is the only gap — and it’s not currently a gap for Baseworks. All five sources agree the other five components are necessary. IBM provides the clean vocabulary; the practitioner sources provide the implementation.

Baseworks Infrastructure Context — The Dual-RAG System

The Baseworks vault already has a search and retrieval layer that none of the five sources explicitly describe, but that is directly relevant to how memory and context retrieval should be designed.

Two parallel systems run on this vault:

System 1 — Obsidian’s graph and wikilink graph Obsidian’s own graph view and backlinks panel provide relational navigation: which notes link to this one, which tags connect these files, what’s the neighbourhood of a given concept. This is inherent to the vault’s wikilink structure.

System 2 — SQLite vault-index (vault-index.db)

Built 2026-04-07. A SQLite database that indexes:

All wikilinks (source, target, resolution status, display text, heading anchors)
All tags (both frontmatter and inline body tags), deduplicated per file
All frontmatter key/value pairs (enabling queries like “all files where entry-path = tokyo-studio-alumni”)

Current scale: 754 files, 2,133 links tracked, 364 unique tags. Full rebuild in 0.38s; incremental in 0.02s.

Why SQLite was added alongside Obsidian’s built-in graph:

Obsidian’s graph provides visual navigation, but cannot efficiently answer structural queries: “what files link to file X?”, “what files share tag Y?”, “what files have this frontmatter value?”. SQL joins handle these efficiently. The database fills a specific gap: relationship and metadata-driven retrieval that would be slow or impossible through full-text indexing alone.

The SQLite index is gitignored — each machine rebuilds its own copy on demand. It rebuilds automatically after every vault sync (via post-sync-hook.sh). Two skills already query it: /vault-audit (health reports) and /draft-response (tag-matching to retrieve precedent files).

How this maps to the agent OS architecture:

In IBM’s framework, this is the Memory Manager — specifically the long-term and structural memory layer. In Simon Scrapes’ framework, it sits between his Level 3 (semantic search) and Level 4 (verbatim recall): it’s structural search, not semantic, and not a full RAG system.

Chase’s position (“you don’t need a full-blown agentic RAG system — Obsidian is just folders”) is partially right for Baseworks. We don’t use a vector database or LightRAG. But we do have more than “just folders”: the SQLite index gives Claude Code efficient structural lookups that pure file-browsing cannot match.

Implication for the agent OS design:

The session start hook (Simon’s Level 2) and AIOS/History/ session log (Milo) should be aware that the SQLite index exists and can be queried. Skills that need contextual retrieval should prefer a vault-index.db query (fast, deterministic) over a full file scan. The memory architecture for Baseworks is:

Layer	Implementation
Level 1 — CLAUDE.md entry point	Thin redirect to me-[name].md + vault-map.md
Level 2 — Session start hook	Force-loads active-projects context
Level 3 — Structural search	SQLite vault-index: backlinks, tags, frontmatter queries
Level 4 — Verbatim recall	Obsidian wikilinks + graph; file reads by path
Level 5 — Knowledge base	Full vault content (23,000+ notes)
Level 6 — Cross-tool DB	Not needed — SQLite covers structural queries; vector DB not warranted at current scale

Simon’s recommendation to skip Levels 5–6 for most use cases holds. The SQLite index already handles what Level 6 would provide for Baseworks’ specific retrieval needs.

On adding a vector database:

A vector database adds one capability the current system doesn’t have: semantic similarity search — finding notes that are conceptually related even without explicit wikilinks or shared tags, using embedding-space proximity.

For Baseworks, this capability is not currently needed. The vault is well-structured with explicit wikilinks, tags, and frontmatter relationships. The retrieval patterns in active use are all structural: “find all files tagged X,” “find all files that link to Y,” “find all files where frontmatter key = value.” These are handled efficiently by the SQLite index. Semantic search helps when you need to find “notes related to a concept I can’t name exactly” across a large, loosely-organized corpus — that is not the shape of the Baseworks vault.

The threshold where a vector DB would make sense:

Regular need for open-ended conceptual discovery (“what relates to X” with no pre-existing link or tag) — this is the primary trigger
Vault grows substantially in untagged/unlinked content (file count alone is not the trigger — a well-organized vault at 10,000 files with explicit relationships still doesn’t need semantic search)
Cross-vault queries spanning multiple operators’ unstructured notes

10,000 files is a re-evaluation signal, not a cutover point. The question to ask is: “Am I finding myself repeatedly unable to locate notes that I know should be related, despite good tagging and linking?” If yes, semantic search fills that gap. If all your retrieval is by tag, wikilink, or named term, the SQLite index handles it at any scale. None of the trigger conditions apply currently. Re-evaluate when retrieval friction appears — not on a file-count schedule.

Media Asset Pipeline — Component Design

Lesson from implementation (2026-06-02): During a Codex design session, carousel image assets were saved directly into the vault. The vault .gitignore blocked binary files from git, but the files existed locally and required manual migration to NAS + CDN. This is a predictable failure mode for any AI tool that doesn’t know the pipeline rule — and the rule belongs in the OS design, not just per-session prompts.

The problem

Any AI tool used for design work (Codex, Claude Design, Canva, Figma) defaults to saving output wherever it’s working. If the working directory is the vault, binaries land in the vault. This causes git bloat, breaks stable CDN URLs, and is only accessible to tools with vault filesystem access — directly opposing the LLM-agnostic portability requirement.

The canonical pipeline (all tools, all sessions)

Creation — design work in any tool (Codex, Claude Design, etc.); output files to Desktop or /tmp/, never directly to the vault.
Handoff — point Claude Code at the output folder.
Upload — Claude Code uploads to Backblaze B2 bucket baseworks-media via b2 CLI. Category folders: campaigns/, blog-articles/, brand/, newsletters/, website/.
CDN URL — https://media.baseworks.com/{category}/{folder}/{filename} — stable, works from any tool, any machine.
NAS copy — files copied to /Volumes/baseworks/media/{same path} as local working copies.
Vault symlinks — symlinks created in the vault assets folder pointing to the NAS path. Resolve when NAS is mounted; gitignored by extension; provide local access without vault binary storage.
HTML/markdown update — preview files and campaign documents updated to CDN URLs.

Why Claude Code handles execution

The execution steps require the b2 CLI (authorized with baseworks-media key), SSH access to synology, and vault filesystem access. These are Patrick’s Mac (or VPS) capabilities. The portable skill describes the workflow; the execution layer performs it. Other tools need only know two things: (1) never save binaries to the vault, and (2) drop assets to Desktop//tmp/ and hand off to Claude Code.

Skill layer design

Layer	Location	Content
Portable skill	`AIOS/Skills/process-media.md`	TRIGGER: binary assets ready. PROCESS: describe files, category, target folder. OUTPUT: CDN URLs + NAS paths + vault symlinks. Execution note: requires Claude Code on Patrick’s Mac or VPS.
Execution wrapper	`.claude/skills/compress-photos/`	Existing skill; handles photo optimization + upload. `process-media` references it for photo assets.
Tool instructions	`AGENTS.md` (Codex), per-tool entry-point files	”Never save binary assets to vault. Drop to Desktop or `/tmp/`. Claude Code handles the pipeline.”

Connection to the Connections layer (Gaspar)

B2 uploads and NAS writes are write-access external integrations. Per Gaspar’s read-only-first rule: both are handled by Claude Code only, with explicit intent per session — not background-automated. CDN reads are read-only for all tools; any AI can reference a CDN URL without access control.

Note on Obsidian Compatibility

Any new folders or files must:

Follow vault frontmatter rules (opening/closing --- delimiters, no duplicate keys, no markdown inside frontmatter)
Not break the sync script — AIOS/ should be added to the sync exclusion list in site/scripts/sync-content.mjs so it doesn’t get pushed to kb.baseworks.com
Use wikilinks for cross-references (not backtick paths)
Not create orphaned files — every new folder needs an index.md

The AIOS/ folder approach (Milo’s naming) works cleanly inside Obsidian and can sit at the vault root. Excluding it from the sync is a one-line config change.

Open Questions for Implementation Discussion

Identity and session management:

me-patrick.md scope — How much of the current CLAUDE.md content belongs in a portable identity file vs staying as Claude Code-specific config? Machine identity, inbox protocol, and git workflow are Claude-specific and should not be in me.md.
Operator detection for ambiguous contexts — For VPS-triggered sessions, what’s the trigger mechanism? Does a cron job always run as “system” with no operator identity, or should each cron routine declare its operator context?
Asia’s me-asia.md — Who writes this? Asia should draft her own preferences section; Patrick or Asia together can draft the shared role description.

Vault and context: 4. vault-map.md scope — Folder structure only, or also note creation conventions and sync pipeline rules? The latter risks bloating it; those could stay in CLAUDE.md. 5. Session start hook content — What gets forced in on every session? vault-map + active projects? brand context? Too much bloats the context window before the first message. Needs testing. 6. voice-profile.md condensation — The voice guides are detailed but long. The injected version should be examples-first, brief. Who condenses them: Patrick, Asia, or Claude?

Technical: 7. AIOS/ sync exclusion — Confirm the exact exclusion pattern for sync-content.mjs before creating the folder. 8. Auto-memory writes — How does claude/memory / AIOS/memory/ stay clean? Without a trim/archive routine, it will grow indefinitely. Define a retention policy before enabling it. 9. Skill refactor scope — All skills at once or domain by domain? The most-used skills first (session-summary, create-newsletter, post-to-group) is the pragmatic order.

LLM-agnostic design: 10. Other tool entry points — If Asia uses Claude Web for some workflows, does she need a SYSTEM_PROMPT.md at the vault root that serves the same role as CLAUDE.md? Or does her me-asia.md plus a brief instruction suffice as a copy-paste system prompt? 11. Skills portability split — Currently all skills live in .claude/skills/. The refactor needs to separate: (a) pure instruction-set skills (TRIGGER → PROCESS → OUTPUT with no Claude Code-specific execution features) → move to AIOS/Skills/ so any tool can reference them; (b) Claude Code-specific skills (hooks, Channels, context inheritance, background tasks) → stay in .claude/skills/. CLAUDE.md points to both layers. Other tools’ entry-point files point to AIOS/Skills/ only, plus their own tool-specific wrappers if needed. Skills in (a) should be treated as the authoritative source; (b) are thin execution wrappers around them where necessary. 12. Multi-machine $HOSTNAME mapping — The CLAUDE.md operator detection needs explicit hostname values for all five machines (Patrick’s MacBook Pro, Patrick’s Mac mini, Asia’s MacBook Air, Asia’s Mac mini, VPS). Confirm actual hostnames before writing the detection logic — hostname in terminal on each machine.

Identity — the third operator context: 13. me-baseworks.md — neutral brand identity file — Patrick and Asia each have a personal identity file. A third file representing the neutral Baseworks voice is needed for content that’s brand-attributed rather than person-attributed: website copy, brand newsletters, Baseworks social posts, formal proposals. This file points to the unified voice guide, the ICP, and brand positioning — the same sources as brand_context/, but framed as an identity file rather than a reference library. Loading me-baseworks.md instead of me-patrick.md signals to the AI that the output should not carry personal voice cues. Needs a decision on whether this is a distinct identity file or whether brand_context/ already serves this purpose with clearer instruction.

Media and asset handling: 14. Multi-tool asset handoff automation — Currently the media handoff requires Patrick to explicitly tell Claude Code “these files are ready.” A more automated version would watch a designated Desktop folder (e.g., ~/Desktop/baseworks-assets-incoming/) and process new files automatically via a LaunchAgent or cron job on Patrick’s Mac. This is a Gaspar Layer 7 automation — it should be drafted as a manual-triggered workflow first, observed for a few weeks, then promoted to automatic if the behavior is reliable. Not required for initial OS implementation; add to backlog after the base pipeline is proven.

Vault symlinks vs gitignore interaction — Symlinks to NAS paths currently resolve via the NAS Finder mount (/Volumes/baseworks/). These symlinks are gitignored by file extension (.png, .jpg, etc.) and exist as local-only convenience pointers. Confirm: (a) the gitignore pattern that covers them, (b) whether Asia’s machines need the NAS mounted at the same path for consistency, and (c) whether broken symlinks on unmounted NAS cause any Obsidian graph or wikilink issues.