How do I install Bilinc?

Copy the http config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Bilinc need an API key?

The publisher lists these environment variables: BILINC_API_KEY.

When was Bilinc last checked?

Last checked 2026-10-16. Hosted agent memory with provenance, contradiction surfacing, and snapshot rollback.

Bilinc MCP server

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.4.1 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.

If your agent needs to...	Bilinc gives it...
Recall a decision before acting	Key-scoped recall with explicit profiles and evidence metadata
Correct a bad memory	`revise`, contradiction-aware state, and provenance-preserving updates
Recover from an unsafe run	Snapshots, diffs, and confirmed rollback
Work across any MCP-compatible agent	A Python SDK, CLI, and stdio MCP adapter

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

You want...	Use...
A hosted memory API for an agent or MCP client	The public cloud-only package from PyPI
Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals	This repository and the architecture guide
A hosted MCP connection without a Python install	The remote MCP setup guide

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

Start in 60 Seconds

Claude connector, without installing Python

Open Customize → Connectors → Add custom connector in Claude, name it Bilinc, and paste https://mcp.bilinc.space/mcp. Sign in and choose read-only or read and write access. The setup guide is bilinc.space/mcp.

For the remote connector in Claude Code:

claude mcp add --transport http --scope user bilinc https://mcp.bilinc.space/mcp

Then run /mcp and authenticate. The remote connector has ten tools; the Python stdio adapter below has eleven. Both connect to hosted Bilinc memory.

Recall in the remote connector shows how long ago each memory was last confirmed and marks entries that are past their review window (90 days for facts, decisions, how-tos and places; 1 day for working notes; events are never marked) as possibly outdated. Nothing is hidden or deleted. Revising a memory with the same value confirms it.

Remote tool	Access	What it does
`recall`	read	Look up memories before acting, with when each was last confirmed.
`list_snapshots`	read	List saved checkpoints, newest first.
`diff`	read	Compare current memory with a checkpoint, showing before → after values.
`status`	read	Workspace, plan, credits, usage, and whether this connection can write.
`remember`	read and write	Store a new memory. It never overwrites an existing key.
`revise`	read and write	Change an existing memory; pass the version you read to refuse the change if it moved since.
`forget`	read and write	Remove a memory from recall, with a reason.
`create_snapshot`	read and write	Save a checkpoint before risky work.
`preview_rollback`	read and write	Show what a rollback would change and issue its confirmation token.
`rollback`	read and write	Restore a checkpoint with that token.

A read-only connection lists only the four read tools.

SDK and CLI

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.4.1

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.

After bilinc login, let the CLI write the setup for your client:

bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
bilinc mcp install                          # plain mcpServers JSON for any other client

{
  "mcpServers": {
    "bilinc": {
      "command": "/path/to/python3",
      "args": ["-m", "bilinc.cloud_mcp"]
    }
  }
}

command is the interpreter that has Bilinc installed, and the adapter reads the key saved by bilinc login, so the config carries no key. On a machine without a saved key, add "env": { "BILINC_API_KEY": "bil_live_..." }.

Eleven tools: the eight-step memory lifecycle plus three review tools.

Tool	What it does
`commit_mem`	Write durable agent state. Each write carries provenance — which run, tool, or operator produced it — and returns a version for optimistic concurrency.
`recall`	Retrieve prior context and decisions before acting. `profile` selects retrieval quality; smart retrieval is that argument, not a separate tool.
`revise`	Deliberately correct something already known. It never creates, so a correction stays distinguishable from an accidental overwrite.
`forget`	Destructive. Remove obsolete state from active recall. A reason is required and is audited; the deleted value is never returned.
`status`	Report the authenticated workspace, plan, capabilities, recall profiles, limits, and usage. Never billed.
`snapshot`	Checkpoint a project before risky work, or list existing checkpoints.
`diff`	Compare a checkpoint against another checkpoint or current state. Values are redacted by default.
`rollback`	Destructive in execute mode. Restore a checkpoint through a free preview plus an explicitly confirmed execute.
`list_memories`	Browse what is stored, ordered by key, with prefix, type and updated-time filters. Read-only and free.
`history`	Show one memory's recorded changes, newest first, with the value before and after. Read-only and free.
`confirm`	Record that a memory is still accurate without resending its value. Costs one write.

Operator and debug tooling — health probes, benchmarks, bulk 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?

Review what Bilinc remembers

Listing, history and export are reads and are not billed. Confirming costs one write.

page = client.list_memories(prefix="agent.", limit=50)       # one page, ordered by key
for entry in client.iter_memories(memory_type="semantic"):   # every page
    print(entry["key"], entry["updatedAt"])

client.history("agent.goal")   # newest changes first (20 by default, up to 100); "truncated" marks older ones
client.confirm("agent.goal", expected_version=page["entries"][0]["entryVersion"])  # still true

backup = client.export()       # every stored memory with its full value, as one dict

Forgetting a memory removes its value from history as well: earlier values of a forgotten memory are not returned.

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

Review what is stored:

bilinc list --prefix agent.          # table of keys, types, update times, value previews
bilinc list --all --json             # every page as JSON
bilinc history agent.goal            # recorded changes, newest first
bilinc confirm agent.goal            # still accurate; the value is unchanged
bilinc export -o bilinc-export.json  # full values; the file is readable only by you

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

Endpoint	Notes
`GET /api/cloud/health`	Public service health. No key, no billing.
`GET /api/cloud/status`	Authenticated capabilities for one key. Never billed.
`POST /api/cloud/memory/commit`	Write.
`POST /api/cloud/memory/recall`	Read.
`POST /api/cloud/memory/revise`	Replace an existing memory.
`POST /api/cloud/memory/forget`	Destructive. Reason required.
`GET /api/cloud/memory/snapshots`	List checkpoints. Free.
`POST /api/cloud/memory/snapshots`	Create a checkpoint.
`POST /api/cloud/memory/diff`	Compare checkpoints. Free.
`POST /api/cloud/memory/rollback/preview`	Free. Mints a confirmation token.
`POST /api/cloud/memory/rollback`	Destructive. Requires that token.

All hosted endpoints share https://bilinc.space. Authenticated memory operations require an active Bilinc Cloud entitlement.

Send an Idempotency-Key header on any write you might retry: the same key with the same payload replays the original result and is billed once, and the same key with a different payload is refused with 409 idempotency_conflict.

Benchmark receipt

Frozen regression receipt, LongMemEval-s cleaned retrieval fixture, 500 questions: Hit@5 98.0%, NDCG@5 0.913, with no LLM reranker and no paid API.

This is a frozen isolated retrieval guardrail — not a current hosted SLA, not an end-to-end agent score, and not a competitor ranking. Published memory-system scores use different metrics, datasets, and levels of LLM assistance, so they are not directly comparable. Present this receipt only with this isolated scope attached.

Evidence map

The repository keeps dated manifests with source state, dataset provenance, runner and metric semantics. These are traceability artifacts, not claims that Bilinc is universally first place.

Lane	Publicly stored evidence	Scope
LongMemEval-s	frozen manifest	Isolated retrieval guardrail
AMB legacy v3	current Modal manifests	Historical generic harness; not Vectorize AMB RAG/judge
Official LoCoMo	retrieval manifests	Retrieval component; not end-to-end QA/F1
Evidence contract	validation rules	Hashes, limitations, and reproducibility boundaries

For the engineering rationale, read Why vector search is not enough for agent memory.

Compare

Answer guides

Contributing

Start with CONTRIBUTING.md. Use Issues for design questions and roadmap feedback; use an issue for a reproducible bug or a scoped implementation task.

Security reports should follow SECURITY.md. Please do not include private memory values, API keys, or production logs in issues, pull requests, benchmark fixtures, or screenshots.

License

BUSL-1.1. See LICENSE.

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.

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.

If your agent needs to...	Bilinc gives it...
Recall a decision before acting	Key-scoped recall with explicit profiles and evidence metadata
Correct a bad memory	`revise`, contradiction-aware state, and provenance-preserving updates
Recover from an unsafe run	Snapshots, diffs, and confirmed rollback
Work across any MCP-compatible agent	A Python SDK, CLI, and stdio MCP adapter

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

You want...	Use...
A hosted memory API for an agent or MCP client	The public cloud-only package from PyPI
Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals	This repository and the architecture guide
A hosted MCP connection without a Python install	The remote MCP setup guide

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

Start in 60 Seconds

Claude connector, without installing Python

For the remote connector in Claude Code:

claude mcp add --transport http --scope user bilinc https://mcp.bilinc.space/mcp

Then run /mcp and authenticate. The remote connector has ten tools; the Python stdio adapter below has eleven. Both connect to hosted Bilinc memory.

Remote tool	Access	What it does
`recall`	read	Look up memories before acting, with when each was last confirmed.
`list_snapshots`	read	List saved checkpoints, newest first.
`diff`	read	Compare current memory with a checkpoint, showing before → after values.
`status`	read	Workspace, plan, credits, usage, and whether this connection can write.
`remember`	read and write	Store a new memory. It never overwrites an existing key.
`revise`	read and write	Change an existing memory; pass the version you read to refuse the change if it moved since.
`forget`	read and write	Remove a memory from recall, with a reason.
`create_snapshot`	read and write	Save a checkpoint before risky work.
`preview_rollback`	read and write	Show what a rollback would change and issue its confirmation token.
`rollback`	read and write	Restore a checkpoint with that token.

A read-only connection lists only the four read tools.

SDK and CLI

pip install -U bilinc
bilinc login
bilinc quicktest

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.4.1

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.

After bilinc login, let the CLI write the setup for your client:

bilinc mcp install --client claude-code     # prints a ready `claude mcp add ...` command
bilinc mcp install --client claude-desktop  # prints the config and where Claude Desktop keeps it
bilinc mcp install                          # plain mcpServers JSON for any other client

{
  "mcpServers": {
    "bilinc": {
      "command": "/path/to/python3",
      "args": ["-m", "bilinc.cloud_mcp"]
    }
  }
}

Eleven tools: the eight-step memory lifecycle plus three review tools.

Tool	What it does
`commit_mem`	Write durable agent state. Each write carries provenance — which run, tool, or operator produced it — and returns a version for optimistic concurrency.
`recall`	Retrieve prior context and decisions before acting. `profile` selects retrieval quality; smart retrieval is that argument, not a separate tool.
`revise`	Deliberately correct something already known. It never creates, so a correction stays distinguishable from an accidental overwrite.
`forget`	Destructive. Remove obsolete state from active recall. A reason is required and is audited; the deleted value is never returned.
`status`	Report the authenticated workspace, plan, capabilities, recall profiles, limits, and usage. Never billed.
`snapshot`	Checkpoint a project before risky work, or list existing checkpoints.
`diff`	Compare a checkpoint against another checkpoint or current state. Values are redacted by default.
`rollback`	Destructive in execute mode. Restore a checkpoint through a free preview plus an explicitly confirmed execute.
`list_memories`	Browse what is stored, ordered by key, with prefix, type and updated-time filters. Read-only and free.
`history`	Show one memory's recorded changes, newest first, with the value before and after. Read-only and free.
`confirm`	Record that a memory is still accurate without resending its value. Costs one write.

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?

Review what Bilinc remembers

Listing, history and export are reads and are not billed. Confirming costs one write.

page = client.list_memories(prefix="agent.", limit=50)       # one page, ordered by key
for entry in client.iter_memories(memory_type="semantic"):   # every page
    print(entry["key"], entry["updatedAt"])

client.history("agent.goal")   # newest changes first (20 by default, up to 100); "truncated" marks older ones
client.confirm("agent.goal", expected_version=page["entries"][0]["entryVersion"])  # still true

backup = client.export()       # every stored memory with its full value, as one dict

Forgetting a memory removes its value from history as well: earlier values of a forgotten memory are not returned.

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

Review what is stored:

bilinc list --prefix agent.          # table of keys, types, update times, value previews
bilinc list --all --json             # every page as JSON
bilinc history agent.goal            # recorded changes, newest first
bilinc confirm agent.goal            # still accurate; the value is unchanged
bilinc export -o bilinc-export.json  # full values; the file is readable only by you

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

Endpoint	Notes
`GET /api/cloud/health`	Public service health. No key, no billing.
`GET /api/cloud/status`	Authenticated capabilities for one key. Never billed.
`POST /api/cloud/memory/commit`	Write.
`POST /api/cloud/memory/recall`	Read.
`POST /api/cloud/memory/revise`	Replace an existing memory.
`POST /api/cloud/memory/forget`	Destructive. Reason required.
`GET /api/cloud/memory/snapshots`	List checkpoints. Free.
`POST /api/cloud/memory/snapshots`	Create a checkpoint.
`POST /api/cloud/memory/diff`	Compare checkpoints. Free.
`POST /api/cloud/memory/rollback/preview`	Free. Mints a confirmation token.
`POST /api/cloud/memory/rollback`	Destructive. Requires that token.

All hosted endpoints share https://bilinc.space. Authenticated memory operations require an active Bilinc Cloud entitlement.

Benchmark receipt

Frozen regression receipt, LongMemEval-s cleaned retrieval fixture, 500 questions: Hit@5 98.0%, NDCG@5 0.913, with no LLM reranker and no paid API.

Evidence map

The repository keeps dated manifests with source state, dataset provenance, runner and metric semantics. These are traceability artifacts, not claims that Bilinc is universally first place.

Lane	Publicly stored evidence	Scope
LongMemEval-s	frozen manifest	Isolated retrieval guardrail
AMB legacy v3	current Modal manifests	Historical generic harness; not Vectorize AMB RAG/judge
Official LoCoMo	retrieval manifests	Retrieval component; not end-to-end QA/F1
Evidence contract	validation rules	Hashes, limitations, and reproducibility boundaries

For the engineering rationale, read Why vector search is not enough for agent memory.

Compare

Answer guides

Contributing

Start with CONTRIBUTING.md. Use Issues for design questions and roadmap feedback; use an issue for a reproducible bug or a scoped implementation task.

Security reports should follow SECURITY.md. Please do not include private memory values, API keys, or production logs in issues, pull requests, benchmark fixtures, or screenshots.

License

BUSL-1.1. See LICENSE.

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

Questions

Bilinc

The short version

Use Bilinc when

Do not use Bilinc when

Choose your surface

Start in 60 Seconds

Claude connector, without installing Python

SDK and CLI

MCP Adapter

Python SDK

Review what Bilinc remembers

CLI

Hosted Endpoints

Benchmark receipt

Evidence map

Compare

Answer guides

Contributing

Links

License

Add this server

Host a copy with our keys and logs.

Related MCP

Related skills

Questions

Bilinc

The short version

Use Bilinc when

Do not use Bilinc when

Choose your surface

Start in 60 Seconds

Claude connector, without installing Python

SDK and CLI

MCP Adapter

Python SDK

Review what Bilinc remembers

CLI

Hosted Endpoints

Benchmark receipt

Evidence map

Compare

Answer guides

Contributing

Links

License