2.8 KiB
2.8 KiB
Org-Agent Memex Architecture Notes
- Core Philosophy: Single User, Single Agent
- Generalization via Environment Variables
- Source of Simplicity
- Future: Linking with Native Org-Agent
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:**
- Standing on established frameworks: Org-mode, Atomic Notes (Zettelkasten) method, GTD, PARA organization—the hard thinking is already done
- Git as state machine: Rather than building custom sync or consensus, we use Git commits as the source of truth for "what's new"
- Immutable sources: Daily logs are append-only; the Scribe never writes to them
- 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.