Constraints
- ■ Runtime files, workflow state, and long-term memory must be separated so agents cannot corrupt the operating system around them.
- ■ Deploys, provider writes, database mutations, and other risky actions stay manual-gated until evidence is available.
- ■ Plans, logs, decisions, and handoffs live as Markdown artifacts so the chat window never becomes the source of truth.
Harness architecture
Deep separation between execution and memory. Main Droid routes every task through strict Gate Ledgers before handing it to specialist workers.
State & Memory
Safety Gates
Execution Engine
Memory stack and MCP infrastructure
Agent memory lives in isolated runtime/config layers with MCP servers and vector databases, not only in loose notes.
Claude Context & Milvus
Local Milvus-backed semantic search lets agents recover code or spec fragments before responding.
Cipher Memory
Persistent graph memory stores project rules, preferences, and recurring constraints through MCP.
DCP dynamic context
Dynamic context packs load the right project material for the active workflow without flooding the prompt.
Obsidian as operational integration layer
Obsidian acts as the write-first UI and integration surface where reports, tasks, context packs, and project hubs remain readable by humans.
Write-first pattern
Agents create final specs, reports, and milestones directly in the vault instead of leaving knowledge trapped in chat.
Dataview indexing
YAML frontmatter and Dataview dashboards turn project hubs, tasks, weekly notes, and reports into live indexes.
Memory handoff
Context packs and research outputs are synchronized back into the knowledge base for future runs.
Command templates
Orchestrator commands create folders, files, and task structures inside the vault with predictable layout.
number: 00/01
project: AI agents obsidian
tags: [obsidian, agents]
status: active
---
AI agents Obsidian
We built an Obsidian agent system on top of Codex...
Arch Notes
- Data flow analysis
- AST parsing logic
Workflow map
Groups operational workflows by purpose so research, agency, development, and PMO work can be routed through explicit commands.
Deep Dive / Research (P0)
concept-to-project .md Creates a project hub, funnel outline, and strategy from a blank starting point.
project-deep-dive .md Runs parallel research, strategy, task decomposition, and handoff for an existing project.
niche-deep-dive .md Researches competitors, ICP, search demand, and content angles for a market niche.
Agency & Funnels (Flatmedia)
agency/intake .md Scopes the client request, deliverable, KPI, and approval gate before execution.
agency/content-loop .md Turns a content calendar into drafts, scripts, and distribution-ready outputs.
fm-offer-funnel-v2 .md Generates landing and email-funnel copy from offer and segment inputs.
Development & PMO
plan / review / test .md Controls code planning, review, and test coverage through deterministic utility workflows.
scaffold-astro / nuxt .md Creates frontend scaffolds only after manual-gated confirmation of scope and stack.
Key workflows
Detailed breakdown of routing and execution processes inside Factory OS.
WF-01: Context Intake (fm.context-intake.v0)
WF-01: Context Intake (fm.context-intake.v0) documents the decision path, validation gate, and handoff state for a repeatable agent run.
- Defines the trigger and expected input state.
- Shows the decision gate before the work proceeds.
- Records the artifact or handoff expected from the run.
- Keeps failure and rollback paths visible to the operator.
flowchart TD
A["Unclear Request"] --> B{"Intake Analysis"}
B --> C["Scope Definition"]
C --> D["Update RunCard"]
C --> E["Update GateLedger"]
D --> F{"Decision Gate"}
E --> F
F -- "Scope Locked" --> G["Bounded Next Step"]
F -- "Missing Data" --> H["Reject / Ask User"]
WF-02: Deep Research (fm.deep-research.v0)
WF-02: Deep Research (fm.deep-research.v0) documents the decision path, validation gate, and handoff state for a repeatable agent run.
- Defines the trigger and expected input state.
- Shows the decision gate before the work proceeds.
- Records the artifact or handoff expected from the run.
- Keeps failure and rollback paths visible to the operator.
flowchart LR
A["Route Approved"] --> B{"Context Scout"}
B --> C["Market Sources"]
B --> D["SEO Doctrine"]
B --> E["Competitors"]
C --> F["Fact Ledger"]
D --> F
E --> F
F --> G{"Validation"}
G -- "Proven" --> H["Research Pack"]
G -- "Unproven" --> I["Blocked Claims"]
WF-03: Astro Page Batch (fm.astro-page-batch.v0)
WF-03: Astro Page Batch (fm.astro-page-batch.v0) documents the decision path, validation gate, and handoff state for a repeatable agent run.
- Defines the trigger and expected input state.
- Shows the decision gate before the work proceeds.
- Records the artifact or handoff expected from the run.
- Keeps failure and rollback paths visible to the operator.
flowchart TD
A["Approved WorkPackage"] --> B["Read Run Card"]
B --> C["Modify Files (Diff)"]
C --> D{"Verification Gate"}
D -- "Pass" --> E["Implementation Report"]
D -- "Fail" --> F["Test Validator"]
F -- "Can Fix" --> C
F -- "Critical" --> G["Rollback Diff"]
AI Modules Ecosystem
The harness modules provide runtime, workflow, review, memory, and artifact services for repeatable AI-assisted delivery.
Factory Runtime
Sandboxed runtime for AI agents so execution stays inside approved boundaries.
M17 Workflows
Registry of deterministic workflow scripts that agents follow instead of inventing process on the fly.
Main Droid
Primary orchestrator that analyzes user intent and routes work to the right specialist.
Sys Architect
Architecture planning agent that designs systems without directly changing code.
Code Reviewer
Read-only reviewer that blocks risky diffs before deployment or handoff.
Context Scout
Discovery worker that searches large codebases and docs without mutation rights.
Gate Ledger
Approval and evidence ledger that stops work until required proof exists.
Run Cards
State files that restore the agent’s memory and task boundary before each run.
Artifact Catalog
Index of generated reports, specs, plans, and proof files.
DCP RPC
Dynamic Context Protocol bridge for loading context packs on demand.
Cipher Memory
Persistent memory layer for global rules, preferences, and past mistakes.
Milvus Vectors
Local vector database for semantic code and documentation search.
Obsidian Sync
Bidirectional handoff channel between agent results and the Markdown vault.
Dataview Hub
Dashboard layer that aggregates YAML frontmatter into live project tables.
Terminal CLI
Slash-command and CLI interface for workflow runs, verification, and harness health checks.
fact: 46 assets cataloged successfully
delta: none found
proof: read-back passed
Markdown-first PMO artifact system
The markdown-first PMO layer stores reports, gate ledgers, run cards, and state registries so automation remains auditable.
Reports Trace Contract
Each significant step writes a report with plan, fact, delta, files, proof, blockers, and next action.
Gate Ledger
Approval ledger records stop conditions, evidence requirements, and manual gates.
State Registry
Run cards, artifact catalogs, and risk registers give agents a canonical state before they answer.
Factory CLI and slash-command interfaces
Routes client requests through intake, research, offer, and delivery-readiness workflows.
Runs an M17 workflow in dry-run mode before mutations are allowed.
Audits system health, limits, provider gates, and approval ledger status.
Captures canonical project state instead of reading scattered logs.
Runs deterministic build, lint, or test proof before a task can be called complete.
Agent operating cycle
A single command can recover project state, choose the approved workflow, run bounded automation, collect proof, and write a handoff instead of leaving the result in chat.
Intent
Identify the real business or engineering goal before turning it into a task.
State recovery
Read the run card, gate ledger, and project state before any files are changed.
Route selection
Choose execute, ask, plan, block, or manual-gated mode depending on risk and missing context.
Bounded work
Run a limited implementation step or delegate to a specialist worker with clear done criteria.
Proof
Run the required verification command or record why the task remains blocked.
Handoff
Write Done, Next, Blockers, Files, and proof references into durable artifacts.
Factory OS operating model
The chaos of chat
The work started from scattered AI chats, lost context, and agents that could not reliably resume interrupted tasks.
Markdown-first memory
A bridge between LLM sessions and Obsidian introduced durable context packs, memory handoffs, and project notes.
The AGENTS protocol
A strict constitution limited what agents could read, write, deploy, or mutate without explicit approval.
Specialist workers
One general assistant became a set of role-specific workers: context scout, coder, tester, reviewer, docwriter, and more.
M17 workflow engine
Forty-six routine operations became deterministic markdown/YAML workflows instead of improvised conversations.
What this proves
Memory layer
Connects Obsidian notes, CLI commands, workflow definitions, and verification gates into one harness.
Worker output is evidence
Turns agent work into repeatable operating procedures instead of ad-hoc prompts and scattered logs.
Mermaid process
Uses Mermaid workflows to document decisions, failure paths, validation gates, and rollback routes.
Obsidian bridge
Separates runtime modules, PMO controls, memory layers, and artifact catalogs so each run is reviewable.
Use the same approach for production systems that need AI acceleration without losing control.
Need an operating system for repeatable AI-assisted delivery?
Factory OS shows how workflows, memory, artifacts, QA, and agent instructions can be governed as one deterministic production environment.