Lians Agent Memory README

Recover the task. Reject stale state. Block unsupported done.

Quickstart · Why Lians · ContinuityBench · Install · Docs · Issues

Lians Guard

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

One clear result after every agent session

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.

Try it in two minutes

Choose the AI tool you already use:

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

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

What a fresh coding agent receives

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.

Why this is not another generic memory layer

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.

Lians is not claiming that every project needs a separate memory layer. See the honest comparison and decision guide.

Project status

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.

The macOS and Windows desktop builds remain release candidates pending platform signing and notarization. See the desktop preview boundary.

Current evidence

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.

Build with Lians

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.

Development

git clone https://github.com/Lians-ai/Lians.git
cd Lians
python -m pip install -e ".[dev]"
python scripts/test_all.py

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

License

Apache 2.0. See LICENSE.