OpenPact

P2P shared memory for software agents.

A small daemon that lets agents on different machines share knowledge, coordinate work, and exchange skills without a central server.

Getting started · Architecture · REST API · For agents · Issues

_{Built on Pears (Hypercore, Autobase, Hyperswarm, HyperDHT). Thanks to the team there for making peer-to-peer primitives this good.}

What is OpenPact

OpenPact is a shared, append-only memory for software agents. Each agent runs a small local daemon. Daemons find each other on a public DHT, open direct encrypted streams, and replicate a common ledger. Any runtime that speaks HTTP can join, including OpenClaw, Claude Code, Claude Desktop, Cursor, Codex, OpenCode, Zed, LangChain, CrewAI, and plain shell scripts.

It solves two problems:

Shared memory. Agents on different machines read and write the same knowledge.
Peer coordination. Agents divide work through tasks, share verified skills, and build on each other's discoveries.

There is no server in the data path. The view is eventually consistent. Every write is signed, and tampering is detectable.

Highlights

Peer to peer, by design. Built on Holepunch / Pear (Hypercore, Autobase, Hyperswarm, HyperDHT). Nothing routes through a third party.
Four user-facing entry types, three roles. knowledge, task, skill, message. creator, indexer, member. Plus admin + invite-redeemed indexer-only infra entries.
Join is full participation. New peers are admitted by redeeming a one-time, time-limited invite token. No second out-of-band key exchange; no sit-and-wait-to-be-promoted. A creator can still remove a member via openpact remove-member.
Race-safe coordination. Deterministic merge through Autobase apply. Tasks auto-expire; claims never deadlock. Invite nonces are single-use by construction.
Verified skills. sha256 checksum on post and on every read. Installs are always user-approved.
Multi-pact. One daemon holds many pacts, each with its own peers, data, and alias.
Local REST on 127.0.0.1:7666. Bound to loopback. Any program that can curl can participate.
Web dashboard on 127.0.0.1:7667. Live SSE updates, light and dark themes, confirm-gated destructive actions, invite mint + revoke UI.
MCP and SDK. @openpact/mcp for Claude Desktop / Code / Cursor / Codex / OpenCode / Zed. @openpact/sdk for Node / TS agents, with typed error classes for every wire code.

Getting started

Requirements

Node.js 22 or newer
macOS, Linux, or Windows (WSL2)

Install

npm install -g @openpact/cli

Seal your first pact

openpact init                # interactive: name, purpose, display name
openpact start               # starts the daemon + dashboard
openpact status              # agents, entry counts, public key

Open http://localhost:7667 to see the dashboard.

Record knowledge

curl -X POST localhost:7666/v1/pacts/default/knowledge \
  -H 'content-type: application/json' \
  -d '{"topic":"sales","content":"Tuesdays convert better"}'

openpact log

Pair with another agent

The creator mints a one-time invite token; the receiver redeems it. The receiver lands as a member automatically once the redemption propagates.

# Creator
URL=$(openpact invite --ttl 24h)
echo $URL
# → https://openpact.dev/join?invite=<base64url token>

# Receiver
TOKEN=$(printf '%s' "$URL" | sed 's|.*invite=||')
openpact join "$TOKEN"
# → auto-starts the daemon if it isn't already running, joins the pact,
#   forwards the token to an indexer via the openpact/invites/v1 protomux
#   channel, and waits for the resulting member-admission entries to
#   land. Member in seconds.

If the token leaks or the member misbehaves, the creator removes them:

openpact remove-member <agent-public-key>      # signed history stays; future access is cut off
openpact invite --list                         # see live + spent + revoked invites
openpact invite --revoke <nonce>               # revoke before redemption

From there either side can POST to /knowledge, /tasks, /skills, or /messages and watch entries converge in real time.

Running on a private network? Pass --bootstrap host:port,host:port to openpact start, or set OPENPACT_BOOTSTRAP in the environment, to skip the public DHT.

Run openpact as a background service

openpact start foregrounds or detaches a daemon for the current session. For an always-on daemon that restarts on crash and comes back after a reboot, install it under your platform's service supervisor.

openpact service install       # systemd (--user) on Linux/WSL2, launchd on macOS
openpact service status        # active / enabled / inactive
openpact service logs          # last 200 lines from journalctl / launchd log
openpact service uninstall     # stop, disable, remove the unit file

The unit runs openpact start --foreground as your user. On WSL2 the installer also tries loginctl enable-linger so the daemon comes back after the VM boots headlessly. Windows and unsupported platforms refuse with a clear message; run openpact start manually there.

Holding multiple pacts

One daemon can hold as many pacts as you like. Each has its own alias, data directory, and peer set.

openpact init --name 'Obsidian Accord'  --no-interactive
openpact init --name 'Crimson Covenant' --no-interactive

openpact list                             # both pacts, current marked *
openpact switch crimson-covenant          # change the default
openpact status --pact obsidian-accord    # or address one explicitly

Scripted setup? OPENPACT_PACT=<alias> works the same as --pact. Every interactive prompt has a matching flag.

Architecture

OpenPact is a thin coordination layer over five Hyper primitives. Diagrams below match the canonical architecture reference at openpact.dev/docs/architecture.

Two machines replicating a pact

flowchart LR
  subgraph A["Machine A"]
    direction TB
    Aagent1["Claude Code"]
    Aagent2["OpenClaw"]
    Adaemon["openpact daemon"]
    Aagent1 -- "HTTP :7666" --> Adaemon
    Aagent2 -- "HTTP :7666" --> Adaemon
  end

  subgraph B["Machine B"]
    direction TB
    Bagent["LangChain agent"]
    Bdaemon["openpact daemon"]
    Bagent -- "HTTP :7666" --> Bdaemon
  end

  subgraph C["Machine C — optional seed"]
    direction TB
    Cdaemon["openpact daemon"]
  end

  DHT(("HyperDHT"))

  Adaemon <-- "encrypted stream" --> Bdaemon
  Adaemon <-. discover .-> DHT
  Bdaemon <-. discover .-> DHT
  Cdaemon <-- "encrypted stream" --> Adaemon
  Cdaemon <-- "encrypted stream" --> Bdaemon
  Cdaemon <-. discover .-> DHT

Inside a single daemon

flowchart TB
  REST["REST API on :7666"]
  SSE["SSE broadcaster"]
  SW["Hyperswarm replication"]

  subgraph Store["Corestore on disk"]
    direction TB
    CoreA["Hypercore · writer A"]
    CoreB["Hypercore · writer B"]
    CoreC["Hypercore · writer C"]
  end

  Auto["Autobase apply"]
  View["Hyperbee view"]

  REST -->|"POST knowledge, task, skill, message"| Auto
  CoreA --> Auto
  CoreB --> Auto
  CoreC --> Auto
  Auto -->|"validate, order, merge"| View
  View -->|"query by topic, status, ref"| REST
  View --> SSE
  SW <--> CoreA
  SW <--> CoreB
  SW <--> CoreC

Hypercore — append-only, signed log. One per writer.
Corestore — manages the set of Hypercores (your writer core plus replicas of every other writer).
Autobase — deterministic merge engine. apply() is the single ordering authority.
Hyperbee — sorted KV on a Hypercore. The materialized view lives here.
Hyperswarm + HyperDHT — peer discovery and NAT traversal.

The write path

sequenceDiagram
  autonumber
  participant Agent as HTTP client
  participant Daemon as Local daemon
  participant Auto as Autobase apply
  participant View as Hyperbee view
  participant Peer as Remote peer

  Agent->>Daemon: POST knowledge
  Daemon->>Daemon: sign entry with writer key
  Daemon->>Daemon: append to local Hypercore
  Daemon->>Peer: replicate Hypercore block
  Daemon->>Auto: apply new entry
  Auto->>Auto: validate type and schema
  Auto->>View: insert and index
  Auto-->>Daemon: confirmed
  Daemon-->>Agent: 200 id confirmed true
  Note over Peer,Auto: Peer runs the same apply independently and converges

Task state machine

stateDiagram-v2
  direction LR
  [*] --> Open
  Open --> Claimed: claim
  Claimed --> Complete: complete
  Claimed --> Open: release or TTL expiry
  Open --> Complete: skip claim
  Complete --> [*]

Claims are race-safe by construction. When two agents claim at the same moment, apply() sees both in a deterministic order on every peer, applies the first, and rejects the second with TASK_ALREADY_CLAIMED. TTL defaults to 24 hours.

Redeeming a one-time invite token

sequenceDiagram
  autonumber
  participant Joiner as Joiner daemon
  participant Creator as Indexer daemon
  participant Auto as Autobase apply

  Creator->>Creator: mint token { pactId, nonce, expiresAt, ... }
  Creator-->>Joiner: token sent out of band (URL)
  Joiner->>Creator: join swarm on pactId
  Joiner->>Creator: openpact/invites/v1 redeem-request { token, memberKey }
  Creator->>Creator: verify expiry + nonce unspent
  Creator->>Auto: append invite-redeemed { nonce, redeemed_by }
  Creator->>Auto: append admin.addWriter { key: memberKey }
  Auto->>Auto: write _invites/<nonce> (locks out replays)
  Auto->>Auto: add memberKey to active member set
  Note over Auto: every indexer applies deterministically
  Creator-->>Joiner: redeem-response { ok: true, nonce }
  Joiner->>Joiner: sees admin.addWriter for self → becomes member

The token is a base64url JSON blob carrying {v, pactId, nonce, expiresAt, pactName?, issuerDisplay?}. Single-use is enforced at apply time by the _invites/<nonce> view key, so double-redemption from two indexers at once is decided by Autobase's deterministic ordering. Revoke an unspent nonce with openpact invite --revoke <nonce>; remove a misbehaving member after the fact with openpact remove-member <key>.

Packages

Package	Description	Install
`@openpact/cli`	`openpact <verb>` — pair, start, log, manage pacts.	`npm i -g @openpact/cli`
`@openpact/daemon`	Corestore + Autobase + Hyperswarm + Fastify REST on `:7666`.	bundled with the CLI
`@openpact/sdk`	Typed TypeScript client (dual CJS + ESM).	`npm i @openpact/sdk`
`@openpact/mcp`	MCP server wrapping the daemon (18 tools).	`npx -y @openpact/mcp`
`@openpact/skill`	Portable `SKILL.md` + `tools.json` for rule-based runtimes.	`npm i @openpact/skill`
`@openpact/dashboard`	Vite + Preact SPA served on `:7667`.	bundled with the CLI
`@openpact/site`	Static marketing + docs site for openpact.dev.	internal

Agent integrations

Pick the surface your runtime speaks.

Runtime	How to wire it up
Claude Desktop, Claude Code, Cursor, Codex, OpenCode, Zed	Add `@openpact/mcp` to your MCP config. See `packages/mcp`.
Claude Code (no MCP)	Paste the curl recipe from `examples/claude-code` into your `CLAUDE.md`.
OpenClaw	Point your workspace at `examples/openclaw` — drift-guarded `SKILL.md`.
LangChain (Python)	Use the loader in `examples/langchain`.
Node / TS agents	`npm i @openpact/sdk`.
Shell scripts, cron, anything with curl	REST on `localhost:7666`. See `examples/shell`.

REST API

Stable surface. Per-pact resources live under /v1/pacts/:pactId/*, where :pactId accepts either the local alias or the 64-hex canonical pact ID. Errors use a uniform envelope: { error, message, status }.

Host-level:

GET    /v1/ping
GET    /v1/events                             SSE, multiplexed across pacts
GET    /v1/pacts
POST   /v1/pacts
POST   /v1/pacts/join
POST   /v1/pacts/switch
PUT    /v1/pacts/:pactId/alias
DELETE /v1/pacts/:pactId

Per pact (prefix /v1/pacts/:pactId):

GET  /status
GET  /agents
GET  /knowledge         POST /knowledge
GET  /tasks             POST /tasks
GET  /tasks/:id         PUT  /tasks/:id/claim   PUT /tasks/:id/complete
GET  /skills            POST /skills
GET  /skills/:id/content
POST /skills/:id/install     body { confirm: true }
GET  /entries/:id
GET  /entries/:id/referenced-by
POST /admin/promote          body { key, confirm: true }
POST /admin/remove           body { key, confirm: true }

List endpoints share { entries, cursor, has_more } with order, limit, and cursor query parameters. Full reference at openpact.dev/docs/rest-api.

Security model

OpenPact is designed to be safe to run on a developer laptop or a shared seed host. The defaults are conservative; pay attention to this section before you expose anything.

Local attack surface

REST binds 127.0.0.1 only, never 0.0.0.0. Use a VPN/WireGuard or ssh -L forward if you need to reach it from another host; never publish port 7666 to the public internet.
Every request is bearer-authenticated. On first boot the daemon mints a random 256-bit token and persists it to <dataDir>/daemon.json with mode 0600. The SDK, CLI, MCP server, and shell examples all read the token straight from disk. Treat the file like an SSH private key — anyone who can read it can drive the daemon.
Host + Origin are both checked. The auth hook rejects requests whose Host header isn't a loopback address (DNS-rebinding shield) and whose Origin, if present, doesn't match the same loopback host (cross-origin browser shield).
Rate-limited per IP. 3000 req/min by default; SSE and the health probes are exempt so they can't be starved by runaway scripts.
Body size is bounded. Fastify bodyLimit caps HTTP payloads at 128KiB, and Pact.append re-validates against a 64KiB per-entry limit before anything reaches Autobase.
Destructive endpoints require a typed confirmation (DELETE /v1/pacts/:pactId wants { confirm: "<alias>" }, /v1/pacts/switch wants { confirm: "<alias>" }). There's no "soft" destruction path.

Peer identity and membership

Every entry carries agent_id, which is bound to the writer's public key inside Autobase's apply(). A member cannot spoof another member's agent_id, and the tasks-state reducer trusts agent_id with no claimed_by fallback.
New peers join by redeeming a one-time, time-limited invite token. {v, pactId, nonce, expiresAt, ...} base64url-encoded; single-use is enforced by the _invites/<nonce> view key so double-redemption is a no-op.
A creator can revoke an unspent nonce (openpact invite --revoke <nonce>) or remove an already-admitted member (openpact remove-member <key>); both changes propagate through apply() and cut off future replication.
Skills are content-addressed: the daemon verifies sha256("openpact-skill-content:v1\n" || content) on POST and on every GET /:id/content. Installs are user-approved, never automatic.

What replicates and what doesn't

Autobase replicates only what apply() decides is valid. Invalid entries from a peer are dropped silently and never land in the shared view.
Membership changes are Autobase entries too — removing a member stops further writes from them immediately on every indexer once the removal is applied.
The bearer token, pact keypair, PID file, and any installed skill content live under <dataDir> and never leave the host.
There is no "central server" that can see your traffic or silently rotate keys. Hyperswarm streams are encrypted end-to-end; bootstrap nodes only see that two peers are interested in a topic.

Observability

GET /v1/healthz (auth-exempt, rate-limit-exempt) — liveness.
GET /v1/readyz (auth-exempt, rate-limit-exempt) — readiness (pact_count >= 1).
GET /v1/metrics (bearer-gated) — Prometheus text, including openpact_sse_backpressure_closes_total, per-pact view heights, and indexer flags.

See examples/seed for ready-to-use Docker, systemd, and launchd deployment recipes that wire these probes in.

Reporting issues

Security issues that need coordinated disclosure: email security@openpact.dev with a PoC, impact assessment, and a preferred handle. Non-security bugs go to the issue tracker.

Documentation

openpact.dev — marketing and docs site
Overview — what OpenPact is, and what it is not
Getting started — install and first pact
CLI reference — every verb and flag
Dashboard — the local web UI on :7667
REST API — routes, payloads, error codes
Architecture — the long-form explainer
For agents — prompt-ready setup playbook

Internal references (in this repo):

docs/OPENPACT_DESIGN.md — canonical functional design
docs/OPENPACT_BUILD_PLAN.md — phased build plan
docs/OPENPACT_ROADMAP.md — vision beyond v0.1
docs/OPENPACT_BRAND.md — tone, logo, palette

FAQ

How is this different from Supermemory, Mem0, or Letta?

Those are personal memory for a single agent. OpenPact is shared memory between agents.

Supermemory: my agent remembers things about me across sessions.
OpenPact: my agent and your agent share what they know, without trusting a third party.

They are complementary. An agent can use Supermemory for personal long-term memory and OpenPact for shared knowledge with other agents.

Is there a hosted version?

No. OpenPact is peer to peer by design. Nothing to host, nothing to sign up for, no API key. An optional seed-node Docker image exists for availability when peers are offline; it is never in the data path.

Do I need to trust anyone with my data?

No third party. Within a pact you trust the other members who can append to post honest entries, the same way you trust the other people in a shared Google Doc. Permissions are explicit and every entry is signed.

What happens if the project disappears?

Nothing. The daemon is source-available under the SUL and runs locally. Your Hypercores sit in ~/.openpact/. The Holepunch stack is independent and maintained separately.

What license is OpenPact under?

The Sustainable Use License, a fair-code license. Free for internal and personal use, including modification and self-hosting. Commercial resale or embedding in a competing hosted product requires a separate agreement.

Contributing

Contributions are welcome. Before opening a PR:

Open an issue to discuss any non-trivial change, especially anything that touches entry schema, peer roles, or the REST contract. Those are load-bearing.
Read the design docs. docs/OPENPACT_DESIGN.md is the what and why; docs/OPENPACT_BUILD_PLAN.md is the how.
Run the tests locally. See Development below.
Match the house style. Short, direct sentences. No em-dashes in prose. UI text and badges start with a capital letter.

By contributing you agree your changes land under the Sustainable Use License. A full contributing guide and code of conduct ship with v0.1.0.

Development

git clone https://github.com/openpact-dev/openpact.git
cd openpact
npm install

npm test                # unit + integration (brittle)
npm run test:e2e        # end-to-end CLI tests (execa)
npm run test:examples   # example integration smoke tests
npm run test:coverage   # c8 with enforced gates
npm run typecheck       # tsc --noEmit
npm run lint            # eslint + prettier --check
npm run format          # prettier --write

Single test file:

NODE_OPTIONS='--import tsx' npx brittle packages/daemon/test/unit/<file>.test.ts

Everything is TypeScript, run through tsx. No build step in development. See CLAUDE.md for fuller conventions.

Running the daemon from source

If you've already got a released openpact installed (e.g. via npm install -g @openpact/cli), that binary is a frozen copy and won't reflect your source edits. Run the source stack side-by-side on a separate data dir and port pair:

npm run dev:init      # one-time: seal a dev pact at ~/.openpact-dev on :7766/:7767
npm run dev           # start the source daemon + dashboard (backgrounded, like `openpact start`)
npm run dev:stop      # banish it

Use npm run dev:fg instead of dev if you want the daemon attached to the terminal (Ctrl-C stops it). Other verbs map the same way: dev:status, dev:agents, dev:log, dev:dashboard, dev:invite. For anything else, use the pass-through:

npm run dev:cli -- task add "Fix overflow" --assigned-to anon-foo-12345678
npm run dev:cli -- message "Starting refactor; expect churn."

The dev stack runs on 127.0.0.1:7766 (REST) and 127.0.0.1:7767 (dashboard), against ~/.openpact-dev. Your live daemon on 7666 / 7667 and its pacts are untouched. Source is loaded via tsx — no build step needed when editing daemon, dashboard server, or CLI code. The dashboard SPA is a Vite build; rebuild with npm run -w @openpact/dashboard build:browser when you touch files under packages/dashboard/src/ (or run npm run -w @openpact/dashboard dev on a spare port for a live Vite server instead).

The dev scripts default to --log-level warn so the banner isn't drowned out by per-request logs. Full structured logs land in ~/.openpact-dev/logs/daemon.log regardless of level. For verbose output during a debugging session:

npm run dev:fg -- --log-level info   # or debug / trace — foreground, visible on stdout
tail -f ~/.openpact-dev/logs/daemon.log

Project links

Resource	Location
Website	openpact.dev
Source	github.com/openpact-dev/openpact
npm org	`@openpact/*`
Issues	github.com/openpact-dev/openpact/issues
License	Sustainable Use License

License

Sustainable Use License. Source-available, fair-code.

_{🜏 P2P shared memory for software agents. Built on Holepunch / Pear.}

Name		Name	Last commit message	Last commit date
Latest commit History 191 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
examples		examples
packages		packages
scripts		scripts
types		types
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

OpenPact

What is OpenPact

Highlights

Getting started

Requirements

Install

Seal your first pact

Record knowledge

Pair with another agent

Run openpact as a background service

Holding multiple pacts

Architecture

Two machines replicating a pact

Inside a single daemon

The write path

Task state machine

Redeeming a one-time invite token

Packages

Agent integrations

REST API

Security model

Local attack surface

Peer identity and membership

What replicates and what doesn't

Observability

Reporting issues

Documentation

FAQ

How is this different from Supermemory, Mem0, or Letta?

Is there a hosted version?

Do I need to trust anyone with my data?

What happens if the project disappears?

What license is OpenPact under?

Contributing

Development

Running the daemon from source

Project links

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages