Bilinc

# Bilinc

<!-- mcp-name: io.github.atakanelik34/bilinc -->

[![PyPI](https://img.shields.io/pypi/v/bilinc.svg)](https://pypi.org/project/bilinc/)
[![Python](https://img.shields.io/pypi/pyversions/bilinc.svg)](https://pypi.org/project/bilinc/)
[![License](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-server-purple.svg)](https://bilinc.space/for/mcp)
[![Release](https://img.shields.io/github/v/release/atakanelik34/Bilinc?display_name=tag&sort=semver)](https://github.com/atakanelik34/Bilinc/releases)
[![CI](https://github.com/atakanelik34/Bilinc/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/atakanelik34/Bilinc/actions/workflows/ci.yml)
<a href="https://pepy.tech/project/bilinc"><img src="https://static.pepy.tech/badge/bilinc" alt="Downloads"></a>

**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.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](#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](docs/architecture.md) |
| A hosted MCP connection | The [MCP setup guide](https://bilinc.space/docs/mcp) |

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

## Start in 60 Seconds

```bash
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:

```bash
pip install -U bilinc==2.3.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:

```bash
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
```

```json
{
  "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_..." }`.

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

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

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](https://bilinc.space/docs/claude-code) ·
[Codex](https://bilinc.space/docs/codex) · [Cursor](https://bilinc.space/docs/cursor) ·
[any MCP client](https://bilinc.space/for/mcp)

## Python SDK

```python
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

```bash
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:

```bash
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:

```bash
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/cl