#+TITLE: Org-Agent Memex Architecture Notes
#+AUTHOR: Amr
#+CREATED: [2026-03-17 Tue]
#+BEGIN_COMMENT
Core architectural principles and design decisions for the org-agent memex system.
#+END_COMMENT

* 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.