{
"markdown": "# Bilinc\n\n\n\n[](https://pypi.org/project/bilinc/)\n[](https://pypi.org/project/bilinc/)\n[](LICENSE)\n[](https://bilinc.space/for/mcp)\n[](https://github.com/atakanelik34/Bilinc/releases)\n[](https://github.com/atakanelik34/Bilinc/actions/workflows/ci.yml)\n![\"Downloads\"](\"https://static.pepy.tech/badge/bilinc\")
\n\n**Hosted memory infrastructure for AI agents: commit, recall, and inspect agent state through one API key, with verification, provenance, and recovery around every write.**\n\nRetrieval 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.\n\nBilinc 2.2.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.\n\n> **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.\n\n## The short version\n\nBilinc is the state layer between an agent and the things it must remember. It keeps memory writes attributable,\ncorrectable, and recoverable instead of treating retrieval as a bag of similar text.\n\n| If your agent needs to... | Bilinc gives it... |\n| --- | --- |\n| Recall a decision before acting | Key-scoped recall with explicit profiles and evidence metadata |\n| Correct a bad memory | `revise`, contradiction-aware state, and provenance-preserving updates |\n| Recover from an unsafe run | Snapshots, diffs, and confirmed rollback |\n| Work across any MCP-compatible agent | A Python SDK, CLI, and stdio MCP adapter |\n\nThe fastest path is `pip install -U bilinc`, `bilinc login`, then `bilinc quicktest` against Bilinc Cloud.\n\n## Use Bilinc when\n\n- A long-running agent — coding, support, research, or a personal assistant — needs to recall prior decisions before a risky action.\n- You need to know which run, tool, or operator produced a piece of agent state.\n- A bad agent run wrote incorrect state and you need a recovery path, not a manual cleanup.\n- Several agents or teammates share one memory surface and you need key-scoped access and usage visibility.\n\n## Do not use Bilinc when\n\n- You only need semantic search over documents — a vector database is the simpler primitive.\n- You require an Apache-2.0 licensed, fully self-hosted runtime. The public package is cloud-only and licensed BUSL-1.1.\n- You want the memory layer to also be your agent framework. Bilinc is the state layer your runtime calls; it does not orchestrate agents.\n\n## Choose your surface\n\n| You want... | Use... |\n| --- | --- |\n| A hosted memory API for an agent or MCP client | The public cloud-only package from PyPI |\n| Local StatePlane, SQLite/PostgreSQL, benchmarks, or internals | This repository and the [architecture guide](docs/architecture.md) |\n| A hosted MCP connection | The [MCP setup guide](https://bilinc.space/docs/mcp) |\n\nThe public package is intentionally smaller than this repository. It does not bundle the internal StatePlane or local\nstorage runtime.\n\n## Start in 60 Seconds\n\n```bash\npip install -U bilinc\nbilinc start\n```\n\n`bilinc start` is the first-run guide. The activation target is simple: reach a\npassing `bilinc quicktest`, which performs one hosted commit, one hosted recall,\nand one Cloud status check.\n\n1. Start the 7-day Bilinc Cloud trial at https://bilinc.space/signup.\n2. Confirm email.\n3. Create one hosted API key in the Cloud dashboard.\n4. Connect the CLI:\n\n```bash\nbilinc login --api-key bil_live_...\nbilinc quicktest\n```\n\nTo reproduce this release exactly:\n\n```bash\npip install -U bilinc==2.2.0\n```\n\nIf you prefer a browser guide, open https://bilinc.space/install and follow the\nsame four-step path.\n\n## MCP Adapter\n\nBilinc exposes a standard Model Context Protocol server over **stdio**, so any\nMCP-compatible client can connect — Claude Code, Codex, Cursor, Hermes-Agent,\nopencode, and others.\n\n```json\n{\n \"mcpServers\": {\n \"bilinc\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"bilinc.cloud_mcp\"],\n \"env\": { \"BILINC_API_KEY\": \"bil_live_...\" }\n }\n }\n}\n```\n\nEight tools — the core memory lifecycle, and nothing else:\n\n| Tool | What it does |\n| --- | --- |\n| `commit_mem` | Write durable agent state. Each write carries provenance — which run, tool, or operator produced it — and returns a version for optimistic concurrency. |\n| `recall` | Retrieve prior context and decisions before acting. `profile` selects retrieval quality; smart retrieval is that argument, not a separate tool. |\n| `revise` | Deliberately correct something already known. It never creates, so a correction stays distinguishable from an accidental overwrite. |\n| `forget` | **Destructive.** Remove obsolete state from active recall. A reason is required and is audited; the deleted value is never returned. |\n| `status` | Report the authenticated workspace, plan, capabilities, recall profiles, limits, and usage. Never billed. |\n| `snapshot` | Checkpoint a project before risky work, or list existing checkpoints. |\n| `diff` | Compare a checkpoint against another checkpoint or current state. Values are redacted by default. |\n| `rollback` | **Destructive in execute mode.** Restore a checkpoint through a free preview plus an explicitly confirmed execute. |\n\nOperator and debug tooling — health probes, benchmarks, export/import, workspace replay — stays\nlocal-only, as do the epistemic read tools for claims, contradictions, and graph queries. The hosted\nadapter does not bundle local runtime internals.\n\nDocumented client setups: [Claude Code](https://bilinc.space/docs/claude-code) ·\n[Codex](https://bilinc.space/docs/codex) · [Cursor](https://bilinc.space/docs/cursor) ·\n[any MCP client](https://bilinc.space/for/mcp)\n\n## Python SDK\n\n```python\nfrom bilinc import CloudClient\n\nclient = CloudClient() # reads BILINC_API_KEY or a key saved by `bilinc login`\n\n# Write, and keep the version for optimistic concurrency.\nwritten = client.commit(\"agent.goal\", {\"ship\": \"reliable memory\"}, memory_type=\"semantic\")\nresults = client.recall(\"agent goal\", limit=5)\n\n# Correct something you already know. Fails if it does not exist.\nclient.revise(\"agent.goal\", {\"ship\": \"verifiable memory\"},\n reason=\"scope corrected\", expected_version=written[\"entryVersion\"])\n\n# Checkpoint before risky work, then see what changed.\nsnapshot = client.create_snapshot(label=\"before-autonomous-run\")[\"snapshot\"]\nclient.diff(snapshot[\"id\"])\n\n# Drop obsolete state. A reason is required and is audited.\nclient.forget(\"agent.goal\", reason=\"superseded by the planner service\")\n\n# Recover. Preview is free; execute is destructive and needs the token.\npreview = client.rollback_preview(snapshot[\"id\"], reason=\"undo bad agent run\")\nclient.rollback(snapshot[\"id\"], confirmation_token=preview[\"confirmationToken\"],\n reason=\"undo bad agent run\")\n\nclient.status() # what can this key do?\nclient.health() # is the service reachable?\n```\n\nFor server, CI, and hosted agent runtimes, store the key as `BILINC_API_KEY`.\n\n## CLI\n\n```bash\nbilinc status # authenticated plan, capabilities, limits, usage\nbilinc health # public service health\nbilinc commit --key agent.goal --value '{\"ship\":\"reliable memory\"}'\nbilinc recall --query \"agent goal\"\nbilinc revise --key agent.goal --value '{\"ship\":\"verifiable memory\"}' --reason \"scope corrected\"\nbilinc snapshot create --label before-autonomous-run\nbilinc snapshot list\nbilinc diff --from-snapshot snap_...\nbilinc forget --key agent.goal --reason \"superseded by the planner service\"\nbilinc doctor\n```\n\nRollback is two stages. Execute takes the token from the preview and never prompts interactively,\nso it stays safe inside automation:\n\n```bash\nbilinc rollback preview --snapshot snap_... --reason \"undo bad agent run\"\nbilinc rollback execute --snapshot snap_... --reason \"undo bad agent run\" \\\n --confirmation-token \n```\n\nUseful first-run commands:\n\n```bash\nbilinc start\nbilinc login --api-key bil_live_...\nbilinc quicktest\nbilinc mcp install\n```\n\n## Hosted Endpoints\n\n| Endpoint | Notes |\n| --- | --- |\n| `GET /api/cloud/health` | Public service health. No key, no billing. |\n| `GET /api/cloud/status` | Authenticated capabilities for one key. Never billed. |\n| `POST /api/cloud/memory/commit` | Write. |\n| `POST /api/cloud/memory/recall` | Read. |\n| `POST /api/cloud/memory/revise` | Replace an existing memory. |\n| `POST /api/cloud/memory/forget` | Destructive. Reason required. |\n| `GET /api/cloud/memory/snapshots` | List checkpoints. Free. |\n| `POST /api/cloud/memory/snapshots` | Create a checkpoint. |\n| `POST /api/cloud/memory/diff` | Compare checkpoints. Free. |\n| `POST /api/cloud/memory/rollback/preview` | Free. Mints a confirmation token. |\n| `POST /api/cloud/memory/rollback` | Destructive. Requires that token. |\n\nAll hosted endpoints share `https://bilinc.space`. Authenticated memory operations require an\nactive Bilinc Cloud entitlement.\n\nSend an `Idempotency-Key` header on any write you might retry: the same key with the same payload\nreplays the original result and is billed once, and the same key with a different payload is\nrefused with `409 idempotency_conflict`.\n\n## Benchmark receipt\n\nFrozen regression receipt, LongMemEval-s cleaned retrieval fixture, 500 questions:\n**Hit@5 98.0%**, **NDCG@5 0.913**, with no LLM reranker and no paid API.\n\nThis is a frozen isolated retrieval guardrail — not a current hosted SLA, not an\nend-to-end agent score, and not a competitor ranking. Published memory-system\nscores use different metrics, datasets, and levels of LLM assistance, so they are\nnot directly comparable. Present this receipt only with this isolated scope attached.\n\n### Evidence map\n\nThe repository keeps dated manifests with source state, dataset provenance, runner and metric semantics. These are\ntraceability artifacts, not claims that Bilinc is universally first place.\n\n| Lane | Publicly stored evidence | Scope |\n| --- | --- | --- |\n| LongMemEval-s | [frozen manifest](benchmarks/evidence/2026-08-04/longmemeval-frozen-final/manifest.json) | Isolated retrieval guardrail |\n| AMB legacy v3 | [current Modal manifests](benchmarks/evidence/2026-08-06/) | Historical generic harness; not Vectorize AMB RAG/judge |\n| Official LoCoMo | [retrieval manifests](benchmarks/evidence/2026-08-06/) | Retrieval component; not end-to-end QA/F1 |\n| Evidence contract | [validation rules](benchmarks/evidence/README.md) | Hashes, limitations, and reproducibility boundaries |\n\nFor the engineering rationale, read [Why vector search is not enough for agent memory](docs/launch/why-vector-search-is-not-enough.md).\n\n## Compare\n\n- [Bilinc vs vector memory](https://bilinc.space/compare/vector-memory)\n- [Bilinc vs Mem0](https://bilinc.space/compare/mem0)\n- [Bilinc vs Zep](https://bilinc.space/compare/zep)\n- [Bilinc vs Letta](https://bilinc.space/compare/letta)\n\n## Answer guides\n\n- [What is AI agent memory?](https://bilinc.space/answers/ai-agent-memory)\n- [How do you roll back an agent memory write?](https://bilinc.space/answers/agent-memory-rollback)\n- [What is an MCP memory server?](https://bilinc.space/answers/mcp-memory-server)\n- [How do you audit what an agent remembered?](https://bilinc.space/answers/audit-agent-memory)\n\n## Contributing\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md). Use [Discussions](https://github.com/atakanelik34/Bilinc/discussions)\nfor design questions and roadmap feedback; use an issue for a reproducible bug or a scoped implementation task.\n\nSecurity reports should follow [SECURITY.md](SECURITY.md). Please do not include private memory values, API keys, or\nproduction logs in issues, pull requests, benchmark fixtures, or screenshots.\n\n## Links\n\n- Website: https://bilinc.space\n- Signup: https://bilinc.space/signup\n- Install guide: https://bilinc.space/install\n- Quickstart: https://bilinc.space/docs/quickstart\n- Cloud quickstart: https://bilinc.space/docs/cloud-quickstart\n- Migration guide: https://bilinc.space/docs/migration-v2\n- MCP setup: https://bilinc.space/docs/mcp\n- PyPI: https://pypi.org/project/bilinc/\n- Machine-readable index: https://bilinc.space/llms.txt · https://bilinc.space/ai-index.json\n- Technical article: [Why vector search is not enough for agent memory](docs/launch/why-vector-search-is-not-enough.md)\n\n## License\n\nBUSL-1.1. See `LICENSE`.\n",
"bytes": 13187,
"sha": "469049688ad7c597b42f5ca2662edb79cf4b5b3ad5d912bcd90240f4c2de19e7",
"repo_slug": "atakanelik34/bilinc",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_atakanelik34_bilinc_b13b8d82/readme"
}