OFFCUT AGENT

Shared memory for AI subagents. One workspace, many agents, one store: an agent writes a decision and another agent — in a different session, on a different machine, holding a different key — recalls it, with the author and the version attached. When two agents give the same named fact different values, OFFCUT raises a conflict instead of letting recency or luck decide.

This repository is the engine: the memory core, the SDK, an MCP server that puts the memory inside Claude Code and any other MCP client, an HTTP API, and a two-layer reward ledger whose cumulative Merkle roots are published on chain. The web console is not part of this repository.

What is in here

Related MCP server: Mnemexa MCP

Memory, as it actually behaves

A record is a fact, a decision, a result or a hypothesis. It carries the agent that wrote it, its topic, its scope and its version.

• Correcting is versioning. Passing correctsRecordId writes a new version linked to the previous one. Nothing is overwritten, so the history of a decision survives the decision.

• Conflicts are raised, not resolved. A record can name a fact — factKey: "storage.backend", factValue: "SQLite". When another agent writes a different value for the same key in the same scope, the server returns an open conflict listing both sides with both authors. Resolving one requires a person, a chosen side and a written rationale, which is stored with the decision.

• Retrieval is ranked, not searched. recall returns what is relevant to a question within the workspace's context limit, with the references needed to inspect the originals.

• Writes are idempotent. Every write takes an idempotencyKey. A retried tool call — which is ordinary in an agent loop — is not a second record.

The nine MCP tools

Getting it running

pnpm install
pnpm setup          # create the SQLite database and seed a demo workspace
pnpm dev            # the API on :4000
pnpm test           # every suite: core, rewards, publisher, acceptance, api, contracts

Connecting the MCP server to Claude Code, against a local database:

pnpm mcp:install    # writes the MCP entry for you
pnpm mcp:check      # handshake, list the tools, call one

Against a server, the client needs nothing but the published package:

claude mcp add offcut \
  -e OFFCUT_API_URL=https://your-offcut-server \
  -e OFFCUT_API_KEY=offcut_sk_... \
  -- npx -y @offcut/mcp-server

Configuration is documented in .env.example. Nothing in this repository requires a key to run locally: without one it uses SQLite in the repository, and the reward publisher does not start unless a contract address is configured.

Rewards

Two layers pay into one ledger, under one root, with one claim:

• Spend — AI spend a provider confirmed. Reports from agents are worth nothing until the provider agrees they happened; only the confirmed figure earns.

• Memory — a record earns one credit, once ever, the first time an agent other than its author retrieves it. Writing memory nobody uses earns nothing.

Each layer has its own daily ceiling and its own rate, and each period's pool is split pro-rata among that period's earners, with a per-earner cap so one workspace cannot take a ceiling-bound period. The two shares are added into one accrual.

Totals are cumulative: every root carries what each address has ever earned, so a distribution that never lands is superseded by the next one rather than lost, and a recipient claims once for everything. The publisher sends a transaction only when the root has moved — quiet periods cost nothing.

Stated plainly, because it is the easiest thing to leave out: this rewards usage, it does not reimburse it. The fund is funded in advance and owes nobody a rate. On a ceiling-bound period a dollar of spend is worth whatever the split makes it worth, which is less.

Checking the claims instead of believing them

pnpm test                 # the full suite
pnpm test:invariants      # the store's own rules
pnpm test:acceptance      # the specification, clause by clause
pnpm test:contracts       # the Solidity, including the claim path

• The reward contract is deployed on Robinhood Chain (chain id 4663) at 0x92c9ef7FD1c2e7423f9b5edDf15ef74eaC4e04Ea, with its implementation verified on Sourcify.

• The deployment record is committed at packages/contracts/deployments/robinhood.json.

• The MCP server and the SDK are on npm as @offcut/mcp-server and @offcut/sdk; npx -y @offcut/mcp-server --help runs the published build without installing anything.

• The specification this was built against is in OFFCUT_AGENT_TZ_EN_v3.1.md, and packages/acceptance executes it.

Status and limits

• The contract is unaudited. It is upgradeable and pausable by its owner, which means the owner can change its behaviour and withdraw the unclaimed pool. That is not trustless, and calling it trustless would be a lie.

• The default store is SQLite, which suits one machine. pnpm use:postgres switches the datasource for a deployment that needs more.

• Reward weight follows what a provider confirms. A subscription — Claude Code's included usage, for instance — is not spend anyone can confirm on your behalf, so it earns from the memory layer and nothing from the spend layer.

• Version control was added to this project late: the history here is a reconstruction over the days the work was done, not a recording of it.

Licence

MIT. See LICENSE.