Recover the task. Reject stale state. Block unsupported done.
Quickstart · Why Lians · ContinuityBench · Install · Docs · Issues
The current-state and completion guard for AI coding agents.
Lians recovers interrupted agent work, rejects stale task state, and blocks
done until the current task is ready for human review.
Your agent can forget the chat. It cannot forget what is finished, what changed, or what still has to pass.
- Recover. Resume a bounded current task across supported Claude Code and Codex sessions.
- Reject stale state. Bind checkpoints to current repository and task state so old evidence is not silently reused.
- Guard completion. Separate measured evidence from an agent's own claims and keep the gate closed while work is missing, unknown, failed, or blocked.
- Require review.
READY FOR HUMAN REVIEWis a handoff to a person, never a claim that the work is correct, approved, or safe to deploy. - Stay local. The free recovery path needs no Lians account, AI password, or provider API key.
Lians works with your existing AI account and editor. It does not replace your model, Git, CI, repository instructions, or human review.
RECOVERED
Task: Fix OAuth callback handling
Next: Re-run the callback integration test
STALE
Reason: The authentication requirement changed after this checkpoint
BLOCKED
Missing: OAuth callback integration test
Untrusted: "tests passed" was reported by the agent, not measured
READY FOR HUMAN REVIEW
Measured locally: callback tests passed
Measured by CI: required checks passed
The trust model is deliberately strict. measured_local, measured_ci, and
human_confirmed evidence can satisfy a criterion. agent_attested and
inferred_activity records remain useful context but cannot open the review
gate. An agent cannot promote its own checkpoint into a trusted class. Trusted
CI evidence requires an exact GitHub attestation and commit match plus an
interactive check-to-criterion mapping; human evidence requires interactive
confirmation. Read why Lians exists, the full
Lians Guard product contract, and the current market
pressure test.
Choose the AI tool you already use:
| Tool | Fastest setup |
|---|---|
| Codex app, CLI, or IDE | One command |
| Claude Code | Two plugin commands |
| Cursor | One-click MCP install |
| Other MCP clients | Minimal MCP setup |
For example, after installing uv, connect Codex with:
codex mcp add lians --env LIANS_MCP_ENABLED_TOOLS=remember,recall,list_memories,correct_memory,forget_memory -- uvx --from "lians-sdk[mcp]" lians-mcpRestart Codex, then save one safe project fact and recover it in a fresh chat.
Local memory is stored in ~/.lians/mcp.db by default. This is the available
free recovery path; the full Guard workflow is currently a developer preview.
Follow the complete quickstart for setup, recovery, correction, deletion, and the Guard preview boundary.
Lians can generate a bounded project handoff instead of replaying a transcript:
Reported complete; verify:
- migrated the orders API to /v2/orders
Still open:
- verify the migration against current Git state
- update documentation
Decisions:
- keep pytest
Changed:
- /v1/orders is stale; use /v2/orders
Next:
- update documentation before touching unrelated UI
The handoff is derived from current Lians state, not a manually maintained summary. Agent-reported work remains visible without being mislabeled as verified completion.
Native memories are convenient when work stays inside one product. General memory is no longer a scarce category. Lians uses local memory for recovery, then focuses on the expensive gap: current task state and evidence-backed readiness.
The current competitive landscape pressure tests this position against native Claude Code, Codex, Cursor, GitHub Copilot, Entire, Factory, and AI review workflows.
| Approach | Best fit | Boundary |
|---|---|---|
| Native tool memory | One AI tool, minimal setup | Usually stays inside that vendor |
AGENTS.md or CLAUDE.md |
Stable repository instructions | Must be maintained manually |
| Transcript replay | Reconstructing one conversation | Large, noisy, and may revive stale decisions |
| Free Lians recovery | Resume current project context across supported tools | Requires a local connection to each tool |
| Lians Guard | Detect stale state and gate readiness with typed evidence | Team workflow is still in developer preview |
Lians is not claiming that every project needs a separate memory layer. See the honest comparison and decision guide.
Lians is under active development. Available recovery features and preview Guard features are separated here so the repository does not imply a production guarantee that does not exist yet.
| Capability | Status |
|---|---|
| Local memory through MCP and Python | Available |
| Codex, Claude Code, and Cursor local recovery setup | Available |
| Inspect, correct, and confirmed permanent deletion | Available |
| Bounded context and signed selection receipts | Available |
| Automatic Claude-to-Codex project handoff | Beta |
| Typed evidence and evidence-backed task gate | Developer preview |
| Local Git workspace fingerprint on checkpoints | Developer preview |
| Automatic stale evidence invalidation | In development |
| Attested GitHub Actions evidence intake | Developer preview |
| Local Guard reporting | Developer preview |
| Shared team queue | Planned |
| Cross-platform clean-install CI | Required by the new Guard workflow; first hosted run pending |
| Guided desktop installer and local control center | Release candidate |
The macOS and Windows desktop builds remain release candidates pending platform signing and notarization. See the desktop preview boundary.
The included Claude-to-Codex continuity fixture recovered 10/10 expected facts, exposed 0 stale facts as current, and produced a 231-token handoff. These are bounded beta results, not a promise that every live coding session extracts perfectly. Run the experiment.
The developing ContinuityBench v0.1 publishes the proposed cross-agent, freshness, correction, erasure, provenance, and boundedness test contract. Its current Lians fixture is evidence for that fixture only; it is not presented as a completed competitor leaderboard.
A separate live test saved a synthetic project fact through Cursor, recalled it in a new Cursor chat and a fresh Claude Code session, and confirmed it was gone after deletion. Read the test method.
The Guard correctness benchmark exercises missing evidence, unknown criteria,
failed constraints, blockers, stale updates, and drift signals. It is a local,
deterministic test of the configured policy, not proof of semantic correctness
or a production outcome. Run packages/lians-easy/benchmarks/task_contract_correctness.py
to inspect the cases.
Use the local Python SDK inside an application:
pip install "lians-sdk[local]"from datetime import datetime, timezone
from lians import LocalLiansClient
memory = LocalLiansClient(db_path=".lians/memory.db")
memory.add(
agent_id="my-agent",
content="The project uses Python 3.12 and pytest.",
event_time=datetime.now(timezone.utc),
)
result = memory.recall(
agent_id="my-agent",
query="Which Python version and test runner should I use?",
)See the install guide for TypeScript, Go, Java, C, framework integrations, and self-hosting.
Running a class, club, hackathon, or campus developer group? Use the student and community kit. Contributors and package integrators can start with Supported paths and repository status.
Advanced capabilities
Lians also includes tools for project-scoped agent handoffs, signed selection and review receipts, local research and browser briefs, temporal reconstruction, lineage, information barriers, confirmed erasure, and bounded formal checks. These capabilities are useful for advanced or governed deployments but are not required for the starter memory workflow.
git clone https://github.com/Lians-ai/Lians.git
cd Lians
python -m pip install -e ".[dev]"
python scripts/test_all.pyRead CONTRIBUTING.md before opening a pull request. Feature ideas, integration requests, and reproducible bugs are welcome in GitHub Issues.
If Lians helps your workflow, star the repository so other AI-tool users can find it.
Apache 2.0. See LICENSE.