Distributed Intent Ledger (DIL)

For a long time now, finding bettter ways to track ephemeral details has been on my mind, especially with the advent of Agentic Engineering.

Have you ever wished your agents and assistants could share memories ... across one laptop to your servers and dev machines ... from Codex to Claude to OpenCode to OpenClaw?

Here's the plan for doing all those things and keeping memories and priorities straight.

Distributed Intent Ledger (DIL) is a local-first, filesystem-native protocol for persistent multi-agent and multi-environment memory coordination. In current deployments, Tailscale is used as the private network fabric for secure cross-machine agent communication and coordination.

Start Every Session Correctly

Make good use of READ_THIS_DIL_FIRST.md: require every AI Agent and AI Assistant to read it at the beginning of every session. This bootstrap step is critical for consistent behavior, correct memory scoping, and reliable cross-agent/cross-machine coordination.

What Sets DIL Apart

What sets DIL apart from other approaches is that it unifies memories and tasks across disparate environments for any assortment of AI Agents and AI Assistants by defining memory as a governed protocol, not just a storage format.

• Deterministic identity and scope boundaries:
  • Runtime-derived machine and assistant identities.
  • Scope-first writes to <machine>/<assistant> with explicit promotion to _shared.
  • Multi-agent collaboration is safe-by-default and auditable.
• Filesystem-native and human-auditable:
  • Plain files, frontmatter, and indexes (Obsidian-friendly).
  • No opaque memory database lock-in.
  • Humans can inspect, repair, and diff records directly.
• Protocolized read/write behavior:
  • Required frontmatter schema.
  • Mandatory retrieval order (local -> machine -> shared).
  • Mandatory index and change-log maintenance.
• Anti-parrot execution proof:
  • Write operations must return concrete file paths and excerpts.
  • Prevents false claims that persistence happened when it did not.
• Cross-agent task canon:
  • Shared canonical registry, lifecycle transitions, allocator, and validation.
  • Decouples task identity from any single runtime/model.
  • Enables reliable handoffs across machines and assistants.
• Mixed-model operational resilience:
  • Script-first, idempotent workflows.
  • Validation gates before side effects.
  • Fail-closed behavior suitable for weaker/local models as well as frontier models.

Scope

DIL defines:

• deterministic runtime identity resolution (machine, assistant)
• scoped write boundaries and promotion rules
• retrieval order across local/machine/shared scopes
• frontmatter and task metadata contracts
• machine and agent registries for routing/capability discovery
• index and change-log maintenance requirements
• validation gates for task mutations

How to Use DIL

Scenario 1: Shared Memory Across All Agents on One Machine

1. Choose a local vault path on that machine.
2. Clone this repository into the vault:
   • git clone https://github.com/zigmoo/distributed_intent_ledger.git
3. In each agent/assistant session, start with:
   • Read ~/READ_THIS_DIL_FIRST.md now and acknowledge.
4. Resolve runtime identity before read/write:
   • machine: hostname -s | tr '[:upper:]' '[:lower:]'
   • assistant: env/process-derived slug (no guessing from folder names)

Scenario 2: Shared Memory Across All Agents on Multiple Machines

1. Create an Obsidian vault and configure remote syncing.
2. Set up Tailscale on each machine and join them to your tailnet.
3. Clone this repository into that synced vault:
   • git clone https://github.com/zigmoo/distributed_intent_ledger.git
4. In each agent/assistant session, start with:
   • Read ~/READ_THIS_DIL_FIRST.md now and acknowledge.

Common Operating Steps (Both Scenarios)

1. Create memory notes via script (preferred):
   • scripts/create_memory.sh --type observations --title "..." --base <vault>
2. Create canonical tasks via script:
   • Personal: scripts/create_task.sh --domain personal --title "..." --project "..." --base <vault>
   • Work: scripts/create_task.sh --domain work --task-id DMDI-12345 --title "..." --project "..." --base <vault>
3. Enforce retrieval order when answering:
   • local assistant scope -> machine scope -> shared policies -> shared global
4. Validate tasks before claiming completion:
   • scripts/validate_tasks.sh <vault>
5. Return proof after writes (anti-parrot rule):
   • changed file paths
   • placement proof (find/tree output)
   • short excerpts from changed files
6. Maintain shared runtime inventories:
   • _shared/_meta/machine_registry.json
   • _shared/_meta/agent_registry.json
   • ensure each agent declares supported formats, runtime profiles, and fallback-LLM behavior

Minimum operating rule: write to <machine>/<assistant> first, promote to _shared only for cross-machine/cross-assistant facts.

License

This project is licensed under the Apache License 2.0. See LICENSE and NOTICE.

Repository Layout

• docs/spec-v1.md: normative protocol contract (MUST/SHOULD/MAY)
• docs/machine-registry-contract.md: machine inventory and runtime host contract
• docs/agent-registry-contract.md: agent capabilities, formats, models, and fallback contract
• schema/: JSON schemas for notes and tasks
• examples/: sample vault structure and records
• scripts/: reference helpers and validators

On Another Note

• I've been working to store collective memory for a long time now... https://threeriversduckclub.com/node/2384/edit