# Memkeeper Harness

> Memkeeper: Harness — a local-first task ledger, dispatcher, and runner for coordinating AI agent workforces. Goals, tasks, and dependencies under TTL leases, with evidence and an append-only audit trail. Deterministic; no required network or LLM.

- **Type:** MCP server
- **Install:** `agentstack add mcp-teflon07-memkeeper-harness`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [teflon07](https://agentstack.voostack.com/s/teflon07)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [teflon07](https://github.com/teflon07)
- **Source:** https://github.com/teflon07/memkeeper-harness

## Install

```sh
agentstack add mcp-teflon07-memkeeper-harness
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

# Memkeeper: Harness

Part of the [Memkeeper](https://github.com/teflon07/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](https://rustup.rs)), 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

```sh
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.

```sh
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](https://github.com/teflon07)
- **Source:** [teflon07/memkeeper-harness](https://github.com/teflon07/memkeeper-harness)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-teflon07-memkeeper-harness
- Seller: https://agentstack.voostack.com/s/teflon07
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.