Distributed Knowledge Base with Git-Based Sharding
Agence is a distributed agent collaboration system that solves persistent memory and multi-tenant isolation through git-based sharding.
┌───────────────────────────────────────────┐
│ Agence Master Repository │
│ (l-agence/agence-master - reference impl) │
└──────────────────┬────────────────────────┘
│
[Git Clone/Pull:]
[CODEX] : Governance
[OBJECTCODE] : CODE-base
[GLOBALCACHE] : RAG-base
[ORGANIC] : Swarm Orchestration (Workflows, tasks etc)
[SYNTHETIC] : DWM-Base
│
┌──────────────┼────────────┐
↓ ↓ ↓
┌────────────┐ ┌────────────┐ ┌────────────┐
│ Agence │ │ Agence │ │ Agence │
│ Shard A │ │ Shard B │ │ Shard C │
│(Team Repo) │ │(Org Repo) │ │(Project) │
└────────────┘ └────────────┘ └────────────┘
│ │ │
[NEXUS] [NEXUS] [NEXUS] : Local States
[HERMETIC] [HERMETIC] [HERMETIC] : Secret-base
l-agence/agence-master (GitHub)git clone l-agence/agence-masterCODEX (Immutable, Versioned)
├─ Principles (maxims)
├─ Laws (constraints)
├─ Rules (best practices)
└─ Lessons (learned insights)
NEXUS (Operational, Ephemeral)
├─ Logs (activity)
├─ Faults (errors)
├─ Sessions (agent state)
└─ Buffers (stdout/stderr/stdin - future)
Sync Strategy:
| Problem | Centralized DB | Git Sharding |
|---|---|---|
| Database Size | Grows unbounded | One per project (small) |
| Compression | Complex, slow | Native git compression |
| Security | Shared access control | Per-repo isolation |
| Scaling | Requires infrastructure | Scales with git |
| Backup | Custom strategy | Git native (distributed) |
Shards are created at git repository boundaries:
Development Organization
├─ Frontend Team
│ └─ repo: ui-framework
│ └─ Agence Shard A (own NEXUS/CODEX)
├─ Backend Team
│ └─ repo: api-services
│ └─ Agence Shard B (own NEXUS/CODEX)
└─ DevOps Team
└─ repo: infrastructure
└─ Agence Shard C (own NEXUS/CODEX)
Key Properties:
.agence/ directory.agence/.gitignore excludes nexus/ (operational state).agence/codex/ and .agence/synthetic/ are versioned┌─ Shard Instance
│ ├─ bin/agence (symlink or copy from master)
│ ├─ codex/ (versioned)
│ │ ├─ PRINCIPLES.md (base + overrides)
│ │ ├─ LAWS.md
│ │ ├─ RULES.md
│ │ └─ agents/ (local personas)
│ ├─ synthetic/ (versioned)
│ │ ├─ lessons/ (project-specific)
│ │ └─ docs/
│ └─ .gitignore (excludes nexus/)
┌─ Not Shared: Instance
│ ├─ nexus/ (local states, not versioned)
│ │ ├─ logs/
│ │ ├─ faults/
│ │ └─ sessions/
│ ├─ hermetic/ (private local knowledge)
│ │ ├─ lessons/ (project-specific)
│ │ └─ docs/
CREATE (^save)
↓
SAVED (session-saved.jsonl)
↓
├─→ RESUME (^resume) → ACTIVE
├─→ HANDOFF (^handoff) → TRANSFERRED
└─→ ARCHIVE (after expiry)
{
"session_id": "69a8f74c",
"created_at": "2026-03-05T03:21:07Z",
"status": "saved",
"agent": "claudia",
"runstate": {
"agent_context": "Current task description",
"execution_stack": "Current working directory, file states",
"memory_state": "Variables, buffers, internal state",
"cursor_position": "Active file and line position",
"todo_list": [
{ "id": 1, "title": "Task 1", "status": "in-progress" }
]
},
"metadata": {
"task_description": "What this session was working on",
"repo": "/path/to/repo",
"priority": "high",
"tags": ["deployment", "urgent"]
}
}
Shard A (Team Frontend)
├─ Agent: Claudia (active)
├─ Session: 69a8f74c (saves state)
│ └─ Export: nexus/sessions/69a8f74c.export.json
│
[Git Commit & Push]
[Manual transfer or CI/CD]
│
Shard B (Team DevOps)
├─ Agent: Ralph (receives)
├─ Import: nexus/sessions/69a8f74c.export.json
└─ Execute: agence ^resume 69a8f74c
└─ Continues with full context
agence <input>
│
├─ "..." → mode_chat (natural language)
├─ "+..." → mode_ai_routed (autonomous planning)
├─ "/..." → mode_external (validated commands) [/commit /pull]
├─ "!..." → mode_system (shells & sessions) [!bash, !aider]
├─ "~..." → mode_private (agence hermetic commands) [~learn]
└─ "^..." → mode_shared (agence synthetic commands) [^learn]
├─ ^init (initialize environment)
├─ ^reload (load all context)
└─ ^save (persist session)
Commands under / are:
Example:
agence /git-status # ✅ Allowed (read-only)
agence /terraform-apply # ❌ Blocked (destructive)
codex/agents/
├─ @claudia # (opus) Principal SRE and architect. Visionary Evolution.
├─ @chad # (GPT) free & cost-optimized but Safe and reliable devops/cloudops. Stability.
├─ @aiko # (haiku) lead CI/CD DevOps SRE, infrastructure prototyping. Disruptive innovator.
├─ @sonya # (sonnet) Full Stack Dev lead and SRE. Deep detailed elegant coding. Backend, data layer.
├─ @ralph # (ralph) Ralph Wiggum iteration loop
├─ @olena # (ollama) free & Secure guard-railed On-premises local Ollama sessions.
├─ @peers # (3-peers) MIT style 3-peer LLM agent weighed consensus. Strategic planning, Unsolvable P1 problems, RCA reviews.
└─ @pilot # (copilot) Copilot agent session. Code review, quality
Each agent has:
Agent A (active)
│
├─ Identify need for specialist
├─ Save session: ^save "Handing off to Ralph for infra"
├─ Determine target: Ralph (DevOps agent)
│
└─ Execute: agence ^handoff ralph
│
├─ Export session to transfer format
├─ Note: "Ralph, vpc implementation"
└─ Return context to user with pointer
User/Agent B
│
├─ Receive handoff pointer
├─ Load: agence ^resume 69a8f74c
└─ Continue from where Agent A left off
User Input: agence "How do I configure TLS?"
↓
Agence (bin/agence)
├─ Detect mode: chat
├─ Load context: codex/LAWS.md, RULES.md
├─ Load agent: codex/agents/claudia.md
├─ Call LLM: Claude Opus
├─ Log call: nexus/logs/llm-calls.jsonl
└─ Output: Structured response
User Command: agence ^save "Halfway through deployment"
↓
Agence (save_session function)
├─ Capture: pwd, git status, todo list, history
├─ Generate: session_id (hex timestamp)
├─ JSON: Create session object
├─ Append: nexus/sessions/session-saved.jsonl
├─ Update: nexus/sessions/INDEX.md
└─ Confirm: "Session 69a8f74c saved"
Later...
User Command: agence ^resume 69a8f74c
↓
Agence (resume_session function - future)
├─ Load: session JSON from JSONL
├─ Restore: pwd, file states, todo list
├─ Reload: agent context and memory
├─ Display: "Resuming deployment task at step 3/8"
└─ Continue: Ready for next command
User: Working with Claudia on API design
User: agence ^handoff ralph "Need infrastructure setup"
↓
Agence (Shard A - Frontend)
├─ Save session: 69a8f74c
├─ Export: nexus/sessions/69a8f74c_ralph.export
├─ Commit: [handoff] Session 69a8f74c from Claudia to Ralph
└─ Sync: Push to shared location (or manual transfer)
User: [Switches to backend repo - Shard B]
Agence (Shard B - Backend)
├─ Import: 69a8f74c_ralph.export
├─ Load agent: Ralph (DevOps/infrastructure specialist)
├─ Resume: agence ^resume 69a8f74c
├─ Context: Full previous conversation, decisions, state
└─ Continue: Ralph picks up from step N with full context
Per-Repository Isolation:
Per-Organization Isolation:
Role | CODEX Access | NEXUS Access | Handoff Rights
──────────────┼──────────────┼──────────────┼────────────────
Agent (local) | Read | Read/Write | Within shard
Agent (cross) | Read | Read (hint) | With approval
User | Read | Read (own) | Full
Admin | Read/Write | Read/Write | Full
nexus/sessions/
├─ session-active.jsonl # Current (hot)
├─ session-saved.jsonl # Recent (warm)
├─ session-completed.jsonl # Old (compress & archive)
└─ archive/
├─ 2026-02.tar.gz (cold)
└─ 2026-01.tar.gz (cold)
| Phase | Target | Features |
|---|---|---|
| V0.1 | ✅ Done | Session save, command routing, NEXUS/CODEX separation |
| V0.2 | ✅ Done | Multi-agent coordination, session resume, architecture docs |
| V0.3 | ✅ Done | Git-based sharding, tmux 1+1, .ailedger, pipe-pane |
| V0.4 | ✅ Done | guard.ts, signal.ts, Docker, PS1, task IDs, ^regen |
| V0.5 | ✅ Done | Skills (29), peers, dispatch, mixed agent routing, security fixes |
| V0.6 | ✅ Done | First public release, cognitive memory (COGNOS), 291 tests |
| V0.7 | ✅ Done | Modular bin/agence split, MCP server, ^ken, ^recon, ledger auto-derive |
| V0.8 | 📍 Next | MLS enforcement + AIPOLICY capability tokens |
| V1.0 | 📋 Planned | Production-ready, Allegiance ledger, multi-org support |
Rationale:
Trade-offs:
Rationale:
Trade-offs:
Rationale:
Trade-offs:
| Term | Definition | |——|————| | tangent | A single execution branch — one agent thread exploring a problem or subtask autonomously. Named for the geometric sense: a line touching the curve at one point, then diverging. | | sequent | An orchestrated set of tangents running in parallel. The swarm scheduler composes sequents to explore multiple solution paths simultaneously. | | resultant | The chosen outcome selected from competing tangents after a tournament. The vector sum of all exploration, collapsed to a single commit/artifact. | | divergent | The point where an exploration path forked from the main line. Recorded for time-travel replay and post-hoc analysis of decision trees. | | chunk | The AST-aware indexing system for codebase knowledge (objectcode). Pure TypeScript, Bun-compiled. Formerly “ChunKing”. | | formtag | Dewey-decimal-like tagging system for general semantic knowledge (synthetic/hermetic). Lightweight context classification. | | mnemonic | Two-tier memory: ephemeral global index + federated per-org stores. Caches frequently accessed chunks/formtags. | | shard | A git repository configured with Agence. Each shard has its own CODEX (rules) and NEXUS (state). | | CODEX | Immutable governance layer: PRINCIPLES, LAWS, RULES, AIPOLICY. Versioned in git. | | NEXUS | Mutable operational state: sessions, logs, faults. Not version-controlled by design. |
Document Version: 0.4.0
Last Updated: 2026-04-10
Status: Active Development