memex/projects/org-skill-memex/docs/ARCHITECTURE.org

Org-Agent Memex Architecture Notes

• Core Philosophy: Single User, Single Agent
  • Why This Scope?
• Generalization via Environment Variables
  • Principle: Build with generalization, keep variable values out**
• Source of Simplicity
  • What makes this project tractable:**
  • What we're NOT building** (which would add complexity):
• Future: Linking with Native Org-Agent
  • Phase 1** (current): OpenClaw orchestrates cloud LLMs using SKILL.md definitions
  • Phase 2** (future): Native `org-agent` (Common Lisp) executes the same skills locally

Core architectural principles and design decisions for the org-agent memex system.

Core Philosophy: Single User, Single Agent

Why This Scope?

The system is deliberately designed for one human, one AI assistant:

• No coordination complexity: One agent owns one workflow (Scribe = Atomic Notes (Zettelkasten) distillation, GTD Manager = task promotion)
• No conflict resolution: Agent reads from immutable sources (daily logs) and writes to separate targets (atomic notes, GTD promotions)
• No multi-agent negotiation: The assistant doesn't delegate to sub-agents; it executes skills directly

This is not a multi-agent orchestration system. It's personal automation.

Generalization via Environment Variables

Principle: Build with generalization, keep variable values out**

All identity-specific and configuration values live in `.env`:

Variable	Purpose
MEMEX_USER	The human user's name (e.g., "Amr")
MEMEX_ASSISTANT	The AI assistant's identifier (e.g., "Agent")
CURRENT_TEXT_MANIPULATION_MODEL	The LLM tier for text processing
MEMEX_* paths	Folder structure (PARA hierarchy)

Skills reference these as `$VARIABLE` in scripts or get instructed to use them. No hardcoded names in skill logic.

Source of Simplicity

What makes this project tractable:**

1. Standing on established frameworks: Org-mode, Atomic Notes (Zettelkasten) method, GTD, PARA organization—the hard thinking is already done
2. Git as state machine: Rather than building custom sync or consensus, we use Git commits as the source of truth for "what's new"
3. Immutable sources: Daily logs are append-only; the Scribe never writes to them
4. Deterministic outputs: Atomic notes have clear rules (concept-filenames, id: backlinks, no dates in names)

What we're NOT building** (which would add complexity):

• Multi-user collaborative editing
• Real-time synchronization across devices
• Agent-to-agent task delegation protocols
• Distributed state management
• Conflict resolution for simultaneous edits

The complexity is in the workflow logic, not the technical infrastructure.

Future: Linking with Native Org-Agent

Phase 1** (current): OpenClaw orchestrates cloud LLMs using SKILL.md definitions

Phase 2** (future): Native `org-agent` (Common Lisp) executes the same skills locally

The interface remains constant:

• Skill definitions in Org-mode format (SKILL.md)
• .env configuration
• PARA folder structure
• Git-based state tracking

When `org-agent` matures, it can read and execute the same skill files we're writing today. The transition from cloud-based to local inference becomes seamless because the specification (Org files) is implementation-agnostic.