Bilinc

Hosted memory infrastructure for AI agents: commit, recall, and inspect agent state through one API key, with verification, provenance, and recovery around every write.

Retrieval answers "what is similar to this?". Long-running agents also need to answer "who wrote this state, was it verified, did it contradict what we already knew, and can we undo it?" — that is the layer Bilinc provides.

Bilinc 2.3.0 on PyPI is the public cloud-only package: a thin Python SDK, CLI, and MCP adapter for Bilinc Cloud. It does not ship the local StatePlane, storage backends, eval, observability, integrations, or server runtime internals.

Frozen regression receipt — LongMemEval-s cleaned retrieval fixture, 500 questions: Hit@5 98.0%, NDCG@5 0.913, no LLM reranker, no paid API. This is an isolated retrieval guardrail, not a current hosted SLA, end-to-end agent score, or competitor ranking — see Benchmark receipt for the full scope and qualification.

The short version

Bilinc is the state layer between an agent and the things it must remember. It keeps memory writes attributable, correctable, and recoverable instead of treating retrieval as a bag of similar text.

The fastest path is pip install -U bilinc, bilinc login, then bilinc quicktest against Bilinc Cloud.

Use Bilinc when

• A long-running agent — coding, support, research, or a personal assistant — needs to recall prior decisions before a risky action.
• You need to know which run, tool, or operator produced a piece of agent state.
• A bad agent run wrote incorrect state and you need a recovery path, not a manual cleanup.
• Several agents or teammates share one memory surface and you need key-scoped access and usage visibility.

Do not use Bilinc when

• You only need semantic search over documents — a vector database is the simpler primitive.
• You require an Apache-2.0 licensed, fully self-hosted runtime. The public package is cloud-only and licensed BUSL-1.1.
• You want the memory layer to also be your agent framework. Bilinc is the state layer your runtime calls; it does not orchestrate agents.

Choose your surface

The public package is intentionally smaller than this repository. It does not bundle the internal StatePlane or local storage runtime.

Start in 60 Seconds

pip install -U bilinc
bilinc login
bilinc quicktest

bilinc login opens your browser. Sign in with Google, GitHub, or email (free, no card required) and approve this computer; the CLI saves its own API key with owner-only permissions. The key never appears in a URL or your terminal. bilinc quicktest then performs one hosted commit, one hosted recall, and one Cloud status check.

• No browser on this machine (SSH, servers, containers): bilinc login --device prints a short code to approve from any browser.
• CI and scripts: bilinc login --api-key bil_live_..., or set BILINC_API_KEY.

To reproduce this release exactly:

pip install -U bilinc==2.3.0

If you prefer a browser guide, open https://bilinc.space/install and follow the same three-step path.

MCP Adapter

Bilinc exposes a standard Model Context Protocol server over stdio, so any MCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent, opencode, and others.

{
  "mcpServers": {
    "bilinc": {
      "command": "python",
      "args": ["-m", "bilinc.cloud_mcp"],
      "env": { "BILINC_API_KEY": "bil_live_..." }
    }
  }
}

Eight tools — the core memory lifecycle, and nothing else:

Operator and debug tooling — health probes, benchmarks, export/import, workspace replay — stays local-only, as do the epistemic read tools for claims, contradictions, and graph queries. The hosted adapter does not bundle local runtime internals.

Documented client setups: Claude Code · Codex · Cursor · any MCP client

Python SDK

from bilinc import CloudClient

client = CloudClient()  # reads BILINC_API_KEY or a key saved by `bilinc login`

# Write, and keep the version for optimistic concurrency.
written = client.commit("agent.goal", {"ship": "reliable memory"}, memory_type="semantic")
results = client.recall("agent goal", limit=5)

# Correct something you already know. Fails if it does not exist.
client.revise("agent.goal", {"ship": "verifiable memory"},
              reason="scope corrected", expected_version=written["entryVersion"])

# Checkpoint before risky work, then see what changed.
snapshot = client.create_snapshot(label="before-autonomous-run")["snapshot"]
client.diff(snapshot["id"])

# Drop obsolete state. A reason is required and is audited.
client.forget("agent.goal", reason="superseded by the planner service")

# Recover. Preview is free; execute is destructive and needs the token.
preview = client.rollback_preview(snapshot["id"], reason="undo bad agent run")
client.rollback(snapshot["id"], confirmation_token=preview["confirmationToken"],
                reason="undo bad agent run")

client.status()   # what can this key do?
client.health()   # is the service reachable?

For server, CI, and hosted agent runtimes, store the key as BILINC_API_KEY.

CLI

bilinc status                 # authenticated plan, capabilities, limits, usage
bilinc health                 # public service health
bilinc commit --key agent.goal --value '{"ship":"reliable memory"}'
bilinc recall --query "agent goal"
bilinc revise --key agent.goal --value '{"ship":"verifiable memory"}' --reason "scope corrected"
bilinc snapshot create --label before-autonomous-run
bilinc snapshot list
bilinc diff --from-snapshot snap_...
bilinc forget --key agent.goal --reason "superseded by the planner service"
bilinc doctor

Rollback is two stages. Execute takes the token from the preview and never prompts interactively, so it stays safe inside automation:

bilinc rollback preview --snapshot snap_... --reason "undo bad agent run"
bilinc rollback execute --snapshot snap_... --reason "undo bad agent run" \
  --confirmation-token <token-from-preview>

Useful first-run commands:

bilinc login              # browser sign-in; --device without a browser
bilinc quicktest
bilinc mcp install
bilinc start              # prints the first-run guide

Hosted Endpoints