mentu

v1.0.6

Published

16 days ago

The Commitment Ledger - Track promises with evidence

0High
0Medium
0Low

rashidazarang

commitment ledger accountability cli evidence append-only github

Mentu

The Commitment Ledger

Where promises are recorded, evidence is required, and nothing is forgotten.

What is Mentu?

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.

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.

Why Mentu?

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.

Installation

npm install -g mentu

Quick Start

Initialize a workspace

cd your-project
mentu init

This creates .mentu/ledger.jsonl — your append-only commitment ledger.

Capture an observation

mentu capture "Customer reported authentication failing on mobile"
# Captured: mem_a1b2c3d4

Create a commitment

mentu commit "Fix mobile authentication bug" --source mem_a1b2c3d4
# Committed: cmt_e5f6g7h8

Claim responsibility

mentu claim cmt_e5f6g7h8
# Claimed: cmt_e5f6g7h8
# Owner: rashid

Do the work, then capture evidence

mentu capture "Fixed in PR #234, deployed to production" --kind evidence
# Captured: mem_i9j0k1l2

Close with proof

mentu close cmt_e5f6g7h8 --evidence mem_i9j0k1l2
# Closed: cmt_e5f6g7h8
# Evidence: mem_i9j0k1l2

Check status

mentu status

# Workspace: your-project
#
# Open (0)
#
# Closed (1):
#   cmt_e5f6g7h8  "Fix mobile authentication bug"  [closed by rashid]

Commands

Core Operations

| Command | Description | |---------|-------------| | mentu init | 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 |

Triage Operations (v0.8)

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

Integrations

| 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:

Commitments trace to memories. Every obligation has an origin.
Closure requires evidence. Proving done, not marking done.
Append-only. Nothing edited. Nothing deleted.

The Ledger

Everything lives in one file:

.mentu/ledger.jsonl

Each line is an operation:

{"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:

genesis:
  version: "1.0"
  created: "2025-07-03T10:00:00Z"

identity:
  workspace: "acme-project"
  owner: "[email protected]"

constitution:
  principles:
    - id: "evidence-required"
      statement: "Commitments close with proof, not assertion"

permissions:
  actors:
    "[email protected]":
      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

Personal accountability

Track your own commitments. Never lose context. Always have proof.

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

Team coordination

Share a ledger. See who's working on what. Verify completion.

mentu status --all

# Open (3):
#   cmt_001  "Fix auth bug"      [claimed by alice]
#   cmt_002  "Update docs"       [claimed by bob]
#   cmt_003  "Review PR #45"     [open]

Agent accountability

Agents claim work and must provide evidence. No more "trust me, it's done."

# Agent claims
mentu claim cmt_001 --actor agent:worker-1

# Agent works, captures evidence
mentu capture "Tests passing, deployed to staging" --kind evidence --actor agent:worker-1

# Agent cannot close directly (Genesis Key constraint)
# Human reviews evidence, closes
mentu close cmt_001 --evidence mem_002

Audit trail

Every decision traceable. Every action recorded. Every closure proven.

mentu log --id cmt_001

# op_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

Global options

| Option | Description | |--------|-------------| | --actor <id> | Override actor identity | | --workspace <path> | Use different workspace | | --json | Output as JSON |

Command options

capture

mentu capture <body> [options]
  --kind <kind>       # Type of observation (e.g., "evidence", "bug_report")
  --ref <id>          # Reference to related memory
  --source-key <key>  # Idempotency key from external system

commit

mentu commit <body> --source <id> [options]
  --tag <tag>         # Add tag (repeatable)

release

mentu release <id> [options]
  --reason <reason>   # Why releasing

annotate

mentu annotate <id> <body> [options]
  --kind <kind>       # Type of annotation (e.g., "comment", "link")
  --ref <id>          # Reference to related record

status

mentu status [options]
  --all               # Show all commitments
  --mine              # Show only my commitments
  --open              # Show only open
  --closed            # Show only closed

log

mentu log [options]
  --limit <n>         # Limit number of entries
  --id <id>           # Filter by record ID
  --op <operation>    # Filter by operation type

Environment Variables

| Variable | Description | |----------|-------------| | MENTU_ACTOR | Default actor identity | | MENTU_WORKSPACE | Default workspace path |

Philosophy

The ledger is sovereign

All state derives from the ledger. Components read and write operations. Nothing else.

Accountability is structural

Not enforced by policy. Enforced by design. Commitments require sources. Closures require evidence.

Local-first

Works offline. Works forever. No server required. Sync is optional.

Governance is optional

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.

# Review untriaged memories
mentu list memories --untriaged

# Link 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_abc

# Record triage session
mentu triage --reviewed mem_001,mem_002,mem_003 --summary "Consolidated auth issues"

GitHub Integration

Sync commitments with GitHub Issues:

# Set up (environment variables)
export GITHUB_ENABLED=true
export GITHUB_TOKEN=ghp_xxx
export GITHUB_OWNER=your-org
export GITHUB_REPO=your-repo

# Push commitment to GitHub
mentu push cmt_abc123 --to github

# Link to existing issue
mentu github-link cmt_abc123 --github 42

# Sync from GitHub
mentu pull --github

See CLI Reference for full command documentation.

API Server

Programmatic access to the ledger:

# Create API key
mentu api-key create --actor your-name
# Save the key - shown only once!

# Start server
mentu serve --port 3000

# Use 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.

git clone https://github.com/rashidazarang/mentu.git
cd mentu
npm install
npm run build
npm test

License

MIT

Documentation

One Line

Git gave code a ledger. Mentu gives commitments a ledger.

npm install -g mentu
mentu init