The Commitment Ledger - Track promises with evidence
npm install mentuThe Commitment Ledger
Where promises are recorded, evidence is required, and nothing is forgotten.
---
Mentu is an append-only ledger for tracking commitments and proof.
You observe something. You commit to doing something about it. You claim responsibility. You produce evidence. You close with proof.
Every step is recorded. Every commitment traces to its origin. Every closure requires evidence. History is permanent.
``bash`
mentu capture "Customer cannot log in"
mentu commit "Fix login bug" --source mem_a1b2c3d4
mentu claim cmt_e5f6g7h8... do the work ...
mentu capture "Fixed in commit abc123" --kind evidence
mentu close cmt_e5f6g7h8 --evidence mem_i9j0k1l2
That's it. Full accountability. Complete lineage.
---
Tickets rot. They sit in backlogs, lose context, get marked done without proof.
Messages scatter. Important decisions live in Slack threads nobody can find.
Memory fades. Who decided what? Why? When? Nobody remembers.
Agents hallucinate completion. They claim success without evidence.
Mentu fixes this.
- Commitments trace to origin. Every obligation links to the observation that created it.
- Closure requires evidence. No marking done. Proving done.
- History is immutable. Append-only. Nothing edited. Nothing deleted.
- State is computed. Replay the ledger, get the truth.
---
`bash`
npm install -g mentu
---
`bash`
cd your-project
mentu init
This creates .mentu/ledger.jsonl — your append-only commitment ledger.
`bash`
mentu capture "Customer reported authentication failing on mobile"Captured: mem_a1b2c3d4
`bash`
mentu commit "Fix mobile authentication bug" --source mem_a1b2c3d4Committed: cmt_e5f6g7h8
`bash`
mentu claim cmt_e5f6g7h8Claimed: cmt_e5f6g7h8
Owner: rashid
`bash`
mentu capture "Fixed in PR #234, deployed to production" --kind evidenceCaptured: mem_i9j0k1l2
`bash`
mentu close cmt_e5f6g7h8 --evidence mem_i9j0k1l2Closed: cmt_e5f6g7h8
Evidence: mem_i9j0k1l2
`bash
mentu status
---
Commands
$3
| Command | Description |
|---------|-------------|
|
| Initialize workspace |
| mentu capture | Create memory |
| mentu commit | Create commitment |
| mentu claim | Take ownership |
| mentu release | Release ownership |
| mentu close | Close with evidence (or as duplicate) |
| mentu annotate | Add annotation |
| mentu status | Show state |
| mentu log | Show history |
| mentu show | Show details |$3
| Command | Description |
|---------|-------------|
|
mentu link | Link memory/commitment to commitment |
| mentu dismiss | Dismiss memory as not actionable |
| mentu triage | Record a triage session |
| mentu list memories | List memories with filters |
| mentu list commitments | List commitments with filters |$3
| Command | Description |
|---------|-------------|
|
mentu config | Manage configuration |
| mentu github-link | Link to GitHub issue |
| mentu push | Push to GitHub |
| mentu pull | Sync from GitHub |
| mentu actor | Manage actor mappings |
| mentu unlink | Remove external link |
| mentu serve | Start API server |
| mentu api-key | Manage API keys |See CLI Reference for complete documentation.
---
The Protocol
Mentu is built on nine operations:
| Operation | What it does |
|-----------|--------------|
|
capture | Creates a memory (observation) |
| commit | Creates a commitment (obligation) |
| claim | Takes responsibility |
| release | Gives up responsibility |
| close | Resolves with evidence (or as duplicate) |
| annotate | Attaches information |
| link | Links memory/commitment to commitment |
| dismiss | Marks memory as not actionable |
| triage | Records a triage session |Two objects:
| Object | What it is |
|--------|------------|
| Memory | Something observed |
| Commitment | Something owed |
Three rules:
1. Commitments trace to memories. Every obligation has an origin.
2. Closure requires evidence. Proving done, not marking done.
3. Append-only. Nothing edited. Nothing deleted.
---
The Ledger
Everything lives in one file:
`
.mentu/ledger.jsonl
Each line is an operation:
jsonl
{"id":"mem_a1b2c3d4","op":"capture","ts":"2025-07-03T10:00:00Z","actor":"rashid","workspace":"default","payload":{"body":"Customer cannot log in"}}
{"id":"cmt_e5f6g7h8","op":"commit","ts":"2025-07-03T10:01:00Z","actor":"rashid","workspace":"default","payload":{"body":"Fix login bug","source":"mem_a1b2c3d4"}}
{"id":"op_00000001","op":"claim","ts":"2025-07-03T10:02:00Z","actor":"rashid","workspace":"default","payload":{"commitment":"cmt_e5f6g7h8"}}
{"id":"mem_i9j0k1l2","op":"capture","ts":"2025-07-03T10:03:00Z","actor":"rashid","workspace":"default","payload":{"body":"Fixed in commit abc123","kind":"evidence"}}
{"id":"op_00000002","op":"close","ts":"2025-07-03T10:04:00Z","actor":"rashid","workspace":"default","payload":{"commitment":"cmt_e5f6g7h8","evidence":"mem_i9j0k1l2"}}
`State is never stored. State is computed by replaying the ledger.
---
Governance
For single users, the ledger is enough.
For teams, add a Genesis Key:
.mentu/genesis.key
The Genesis Key defines:
- Who can do what (permissions)
- What requires approval (constraints)
- How the workspace is governed (constitution)
Example:
yaml
genesis:
version: "1.0"
created: "2025-07-03T10:00:00Z"identity:
workspace: "acme-project"
owner: "rashid@acme.com"
constitution:
principles:
- id: "evidence-required"
statement: "Commitments close with proof, not assertion"
permissions:
actors:
"rashid@acme.com":
operations: [capture, commit, claim, release, close, annotate]
"agent:worker":
operations: [capture, claim, release, annotate]
# cannot commit or close
constraints:
require_claim:
- match: all
require_human:
- operation: close
match: { tags: [financial] }
`---
Use Cases
$3
Track your own commitments. Never lose context. Always have proof.
bash
mentu capture "Idea for blog post about X"
mentu commit "Write blog post about X" --source mem_001
... weeks later ...
mentu status # It's still there, waiting
`$3
Share a ledger. See who's working on what. Verify completion.
bash
mentu status --allOpen (3):
cmt_001 "Fix auth bug" [claimed by alice]
cmt_002 "Update docs" [claimed by bob]
cmt_003 "Review PR #45" [open]
`$3
Agents claim work and must provide evidence. No more "trust me, it's done."
bash
Agent claims
mentu claim cmt_001 --actor agent:worker-1Agent works, captures evidence
mentu capture "Tests passing, deployed to staging" --kind evidence --actor agent:worker-1Agent cannot close directly (Genesis Key constraint)
Human reviews evidence, closes
mentu close cmt_001 --evidence mem_002
`$3
Every decision traceable. Every action recorded. Every closure proven.
bash
mentu log --id cmt_001op_005 close 2025-07-03T15:00:00Z rashid cmt_001
mem_002 capture 2025-07-03T14:55:00Z agent:worker "Tests passing..."
op_003 claim 2025-07-03T10:30:00Z agent:worker cmt_001
cmt_001 commit 2025-07-03T10:00:00Z rashid "Fix auth bug"
mem_001 capture 2025-07-03T09:55:00Z rashid "Customer reported..."
`---
Options
$3
| Option | Description |
|--------|-------------|
|
| Override actor identity |
| --workspace | Use different workspace |
| --json | Output as JSON |$3
capture
`bash
mentu capture [options]
--kind # Type of observation (e.g., "evidence", "bug_report")
--ref # Reference to related memory
--source-key # Idempotency key from external system
`commit
bash
mentu commit --source [options]
--tag # Add tag (repeatable)
`release
bash
mentu release [options]
--reason # Why releasing
`annotate
bash
mentu annotate [options]
--kind # Type of annotation (e.g., "comment", "link")
--ref # Reference to related record
`status
bash
mentu status [options]
--all # Show all commitments
--mine # Show only my commitments
--open # Show only open
--closed # Show only closed
`log
bash
mentu log [options]
--limit # Limit number of entries
--id # Filter by record ID
--op # Filter by operation type
`---
Environment Variables
| Variable | Description |
|----------|-------------|
|
| Default actor identity |
| MENTU_WORKSPACE | Default workspace path |---
Philosophy
$3
All state derives from the ledger. Components read and write operations. Nothing else.
$3
Not enforced by policy. Enforced by design. Commitments require sources. Closures require evidence.
$3
Works offline. Works forever. No server required. Sync is optional.
$3
Single user? Just use the ledger. Team? Add a Genesis Key. The core stays the same.
---
What Mentu Is Not
Not a task manager. Tasks are assignments. Commitments are obligations with lineage.
Not a ticket system. Tickets are forms. Memories are observations. Commitments are promises.
Not a database. State is computed, not stored. The ledger is the truth.
Not a workflow engine. Mentu records what happened. Automation is a layer on top.
---
Triage Layer
Convert volume into clarity. Many observations become few commitments.
`bash
Review untriaged memories
mentu list memories --untriagedLink related memories to a commitment
mentu link mem_001 cmt_abc --kind related --reason "Same issue"Dismiss non-actionable feedback
mentu dismiss mem_002 --reason "Feature request, added to roadmap"Close duplicate commitment
mentu close cmt_xyz --duplicate-of cmt_abcRecord triage session
mentu triage --reviewed mem_001,mem_002,mem_003 --summary "Consolidated auth issues"
`---
GitHub Integration
Sync commitments with GitHub Issues:
bash
Set up (environment variables)
export GITHUB_ENABLED=true
export GITHUB_TOKEN=ghp_xxx
export GITHUB_OWNER=your-org
export GITHUB_REPO=your-repoPush commitment to GitHub
mentu push cmt_abc123 --to githubLink to existing issue
mentu github-link cmt_abc123 --github 42Sync from GitHub
mentu pull --github
`See CLI Reference for full command documentation.
---
API Server
Programmatic access to the ledger:
bash
Create API key
mentu api-key create --actor your-name
Save the key - shown only once!
Start server
mentu serve --port 3000Use the API
curl http://localhost:3000/status \
-H "Authorization: Bearer mentu_key_xxx"
`See API Reference for complete documentation.
---
Roadmap
- [x] Core ledger and CLI (v0.1)
- [x] Genesis Key governance (v0.1)
- [x] GitHub integration (v0.2)
- [x] API server (v0.3)
- [x] Terminal Bridge (v0.5)
- [x] Integration Layer (v0.6)
- [x] Web UI (v0.6.1)
- [x] Triage Layer (v0.8)
- [ ] Sync service
- [ ] Linear/Jira connectors
See Development Roadmap for details.
---
Contributing
Mentu is open source. Contributions welcome.
bash
git clone https://github.com/rashidazarang/mentu.git
cd mentu
npm install
npm run build
npm test
`---
License
MIT
---
Documentation
- Quick Start Guide
- CLI Reference
- API Reference
- Genesis Key Guide
- Protocol Specification
---
One Line
Git gave code a ledger. Mentu gives commitments a ledger.
bash
npm install -g mentu
mentu init
``