activity-mesh

README

activity-mesh

Shared activity log for multi-machine, multi-runtime AI agent setups. Agents see what other agents did — without explicit tool calls, without bloating context, across all OSes.

Status: v1 in development. MIT. Single-user / personal-infra focus.

The problem

Run AI agents across multiple machines and runtimes — Claude Code sessions, custom agents on remote hosts, scheduled bots, CLI tools. Each agent has its own memory: provider auto-memory, project notes, vector stores, wiki-style knowledge bases.

The gap: when one agent does something important, other agents don't know. Cross-system awareness is missing. Existing options don't fit personal infra: vendor-locked SaaS (Mem0/Letta/Zep), heavy databases (Postgres), or ad-hoc shared files that drift.

What it solves

A shared activity log that is:

1. Auto-captured — filesystem watchers + git hooks + session hooks emit events without agent intervention.
2. Auto-injected — UserPromptSubmit hook detects intent and injects a scoped slice into the agent's context invisibly. Empty when no events match.
3. Token-cheap — typical injection ~180 tokens; explicit budget envelope.
4. Cross-machine — per-host JSONL shards synced via Syncthing (zero conflicts by construction).
5. Cross-OS — single Go binary cross-compiled for macOS/Linux/Windows; YAML-described supervisors (launchd/systemd/Task Scheduler) and watchers (fswatch/inotify/USN).
6. Coexists — adds a history layer (when/who) on top of existing memory layers (state truth, knowledge, semantic recall) — clear boundary rules, no replacement.
7. Self-monitoring — 19 health checks, dead-man heartbeat (independent process), weekly digest, recovery runbook.
8. Privacy-first — 3-tier redaction (regex + entropy + NER) at write time, before file hits disk.

How it works

┌─────────────────┐                         ┌─────────────────┐
│  host A         │   Syncthing             │  host B         │
│                 │ ◄────────────────────► │                 │
│  per-host JSONL │  per-host JSONL shards  │  per-host JSONL │
│  daemon :7459   │                         │  daemon :7459   │
│  MCP server     │                         │  MCP server     │
└────────▲────────┘                         └────────▲────────┘
         │                                           │
         │  query / emit / inject                    │
         │                                           │
   ┌─────┴─────┐                              ┌─────┴─────┐
   │  agent A  │                              │  agent B  │
   └───────────┘                              └───────────┘

• Append-only per-host JSONL shards (one host writes one shard, never two writers per file → zero merge conflicts).
• ULID + monotonic_seq for deterministic ordering.
• SQLite + FTS5 indexer for sub-100ms search.
• HTTP daemon at :7459 for query and emit; MCP server for IDE/agent integrations.
• Open registries (kinds.yaml, scopes.yaml, agents.yaml, redaction.yaml) — schema is data, not code.

Quick start

# install (mac/linux)
curl -fsSL https://raw.githubusercontent.com/Surdeddd/activity-mesh/main/installers/bootstrap.sh | bash

# emit
activity-log emit --kind decision --scope project:foo --summary "switched to Bun.fetch"

# query
activity-log query --hours 24

# query daemon (HTTP)
curl 'http://localhost:7459/recent?scope=project:foo&hours=24&limit=20'
curl 'http://localhost:7459/search?q=billing+oauth&limit=10'
curl 'http://localhost:7459/digest?window=today&group_by=scope'

# health
bash health/master.sh | jq .summary

Building

make build         # cross-compile CLI + watcher (no cgo)
make build-daemon  # native build daemon (cgo + sqlite_fts5)
make verify        # vet + test + shellcheck

The daemon needs cgo for the SQLite FTS5 driver. Cross-compile from macOS to other Macs works; for Linux/Windows build natively on the target.

Layout

cmd/activity-log/      # Cobra CLI (init, emit, query, status)
cmd/activity-watcher/  # fsnotify daemon
server/                # HTTP query daemon (:7459)
pkg/event/             # ULID + redaction + sanitize
pkg/redact/            # 14 regex patterns + Shannon entropy ≥4.5
pkg/index/             # SQLite FTS5
pkg/registry/          # YAML loader/validator
mcp/                   # Node stdio MCP server
hooks/                 # SessionStart digest + UserPromptSubmit auto-context
health/                # 19 checks + dead-man heartbeat + master runner
installers/            # bootstrap.sh / .ps1 + launchd/systemd templates
registries/            # kinds.yaml / scopes.yaml / agents.yaml / redaction.yaml

Layered memory model

activity-mesh is a single layer in a stack — it's the history layer. Recommended boundary:

layer	role	example query
state truth	active rules, current preferences	"what's our policy on X?"
knowledge wiki	patterns, decisions, methodology	"how do we handle Y?"
activity-mesh	operational history	"when did Z happen / who did Z?"
semantic index	recall by association	"things related to X"

History does not replace state truth. Don't cite activity events as canonical state — query the state layer first.

Roadmap

• v1: cross-machine sync, auto-context injection, MCP integration, health monitoring (current)
• v2: tier-3 NER redaction (offline weekly batch), digest snapshots, compactor for >90-day events
• v3: Linux + Windows installer parity, multi-runtime SDK adapters

See ROADMAP.md for detailed milestones.

Inspiration

This project was inspired by Andrej Karpathy's LLM Wiki essay and his broader thinking on LLMs as compilers — separate the spec source (versioned schema, redaction rules, registries) from the output artifact (events). The same separation drives the design here: registries are spec; events are artifact.

License

MIT.