Memkeeper Harness

Goals in, evidence out, with a lease, an audit trail, and a deterministic ledger in between.

Memkeeper: Harness

Part of the Memkeeper family.

> Memkeeper is the open-source, local-first control plane that AI agents run on: durable memory, project context, coordinated task handoffs, and deny-by-default permissions, all deterministic and on your own machine.

A local-first task ledger, dispatcher, and runner for coordinating AI agent workforces. The Harness tracks goals, tasks, and dependencies; hands work to agents under TTL+heartbeat leases; records evidence and an append-only audit trail; routes tasks to agents by role; and accepts or rejects each result against an output envelope.

• Deterministic ledger. A SQLite store with goals, tasks, dependencies,

leases, evidence, and task events. The core is clock-free: time is passed in explicitly so lease math and expiry sweeps are testable. Every mutation is a short, committed transaction; no LLM call ever runs inside one.

• TTL + heartbeat leases. A claim is a lease kept alive by a heartbeat. A

crashed agent and a slow agent look the same from outside, so recovery is driven by TTL expiry, never by liveness detection. A failed task blocks its dependents.

• Role-based dispatch. Given a goal and a set of available agent slots, the

dispatcher matches claimable tasks to slots by role and claims each under a lease. It decides who works on what, not how, fully deterministic, no LLM calls.

• Output-envelope acceptance. The runner builds task context, invokes an

executor, then validates the result against an envelope. Malformed output, a missing envelope, or an unknown status fails the task loudly with the raw output preserved as evidence, rather than being silently accepted.

> Status: pre-release (v0.1). The ledger schema and CLI may change before 1.0.

> ⚠️ Early prototype. Newer and less battle-tested than the rest of the > Memkeeper family. Expect rough edges; not recommended for production yet.

> ⚠️ Not a sandbox. The runner executes whatever agent command it is given > (-- or a headless claude agent). It applies no isolation or > capability gating to that work. Pair it with a separate sandbox/policy layer if > you need containment. See [SECURITY.md](SECURITY.md).

> ℹ️ Generated release mirror. This repo is generated from a private > development repo and published as releases. The main branch may be > regenerated, so pin to tagged releases (or the release artifacts) rather > than to arbitrary main commits. See [CONTRIBUTING.md](CONTRIBUTING.md) for > how to contribute; issues, security reports, and design feedback are the best > paths today.

Workspace layout

| Crate | Role | |---|---| | harness-core | The durable SQLite task ledger: goals, tasks, dependencies, TTL+heartbeat leases, evidence, and the append-only task-event audit trail. | | harness-planner | Turns a goal into a task graph automatically: a Planner proposes tasks with roles and dependencies, which is validated (unique keys, no dangling/self-deps, no cycles) and committed atomically. | | harness-dispatch | The routing layer: match claimable tasks to available agent slots by role and claim each under a lease. | | harness-runner | Closes the loop from "claimed" to "finalized": builds task context, invokes an Executor, and accepts/rejects the result against an output envelope. | | harness-cli | The harness binary: a thin command surface over the ledger, planner, dispatcher, and runner. | | claude-invoke | The shared headless claude -p primitive (flags, auth, output-envelope parse) the planner and Claude executor call. |

Prerequisites

• Rust toolchain (stable, via rustup), edition 2021,

so Rust 1.56 or newer. SQLite is vendored via rusqlite (bundled), so no system SQLite is required.

• For the --claude planner/executor or a memkeeper context provider: the

corresponding claude / retriever binary on PATH. Both are optional.

Build & test

cargo build --release
cargo test --workspace

Usage

The store defaults to $HOME/.harness/ledger.sqlite; override it with HARNESS_STORE or --store . Pass --now to override the clock for deterministic scripting and tests. Queries print JSON; mutations print a one-line JSON acknowledgement. Exit codes: 0 success, 1 ledger error, 2 usage error.

H=./target/release/harness

# Create a goal.
$H goal create "Ship the auth refactor" --constraints "no breaking changes"

# Decompose the goal into a task graph automatically: the planner proposes,
# the harness validates (no cycles/dangling deps) and writes it atomically.
# --dry-run previews the plan without writing; --role constrains the vocabulary.
$H plan 1 --claude --dry-run
$H plan 1 --claude --role research --role implement --role review

# ...or build the graph by hand instead. Express a dependency: task 2 waits on 1.
$H task add 1 reviewer "Review the auth diff"          # -> {"ok":true,"task_id":1}
$H task add 1 implementer "Apply review feedback"
$H task dep 2 1

# Claim a task under a 300s lease, heartbeat it, attach evidence, complete it.
$H task claim 1 agent-a --ttl 300
$H task heartbeat 1 agent-a --ttl 300
$H task evidence 1 note "looks good, two nits" --agent agent-a
$H task complete 1 agent-a

# Inspect state.
$H goal claimable 1          # tasks now unblocked
$H task show 2
$H task events 2
$H task evidence-list 1

# Reclaim tasks whose leases have expired.
$H sweep

# Dispatch: match claimable tasks of goal 1 to available agent slots by role.
$H dispatch 1 --slot agent-a:reviewer --slot agent-b:implementer --ttl 300

# Run a claimed task end-to-end with a headless claude agent...
$H run 1 agent-a --claude --model sonnet
# ...or with any executor program (task context is written to its stdin as JSON,
# an output envelope is read from its stdout):
$H run 1 agent-a -- my-agent --flag
# ...optionally wiring in a deterministic memkeeper context pack:
$H run 1 agent-a --claude --memkeeper memkeeper --max-items 5

License

Dual-licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE) at your option.

Contributing

Issues and pull requests are welcome. Contributions require signing the project [Contributor License Agreement](docs/CLA.md), the CLA bot prompts you on your first pull request; you keep the copyright to your contributions. See [CONTRIBUTING.md](CONTRIBUTING.md).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: teflon07
• Source: teflon07/memkeeper-harness
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.