Lians

<p align="center">
  <a href="https://github.com/Lians-ai/Lians">
    <img src="docs/assets/logo-blue.png" width="420" alt="Lians">
  </a>
</p>

<p align="center">
  <a href="https://www.lians.ai/">Website</a>
  -
  <a href="https://github.com/Lians-ai/Lians/tree/master/docs">Docs</a>
  -
  <a href="docs/install.md">Install</a>
  -
  <a href="https://github.com/Lians-ai/Lians#self-hosted-quickstart">Quickstart</a>
  -
  <a href="https://github.com/Lians-ai/Lians/stargazers"><strong>Star Lians</strong></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/lians-sdk">
    <img src="https://img.shields.io/pypi/v/lians-sdk?color=%2334D058&label=pypi%20package" alt="PyPI version">
  </a>
  <a href="https://pypi.org/project/lians-sdk">
    <img src="https://img.shields.io/pypi/dm/lians-sdk?label=pypi%20downloads" alt="PyPI downloads">
  </a>
  <a href="https://github.com/Lians-ai/Lians">
    <img src="https://img.shields.io/github/commit-activity/m/Lians-ai/Lians/master?style=flat-square" alt="GitHub commit activity">
  </a>
  <a href="https://www.npmjs.com/package/@lians-ai/lians">
    <img src="https://img.shields.io/npm/v/%40lians-ai%2Flians?label=npm" alt="npm version">
  </a>
  <a href="https://registry.modelcontextprotocol.io/?q=io.github.ebeirne%2Flians">
    <img src="https://img.shields.io/badge/MCP-Official%20Registry-blueviolet" alt="MCP Official Registry">
  </a>
  <a href="LICENSE">
    <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0">
  </a>
</p>

<p align="center">
  <a href="docs/benchmarks/README.md"><strong>Reproducible benchmark evidence and offline quality gates</strong></a>
  <br />
  <a href="docs/benchmarks/riad-1.md"><strong>RIAD-1: decision reconstruction benchmark</strong></a>
  · <a href="https://github.com/Lians-ai/Lians/actions/workflows/riad-1.yml"><strong>CI receipts</strong></a>
</p>

---

[Lians](https://github.com/Lians-ai/Lians) is the **cross-platform
decision evidence and reconstruction layer for regulated AI**. It gives
compliance, model-risk, and operational-risk teams one record of what an agent
knew, what it retrieved, which policy governed it, which tools ran, who
reviewed it, and what changed later.

The durable moat is neutrality. A firm can run agents across Bedrock, Azure
OpenAI, Anthropic direct, and open-source runtimes while keeping one portable
evidence record outside every provider.

Every write is preserved as a governed temporal record and compiled into a
typed memory artifact. Every recall can run in `fast`, `deep`, or `reconstruct`
mode and returns a content-addressed receipt that can bind automatically to a
Decision Envelope. See
[decision evidence and reconstruction](docs/decision-evidence.md), the
[normative completeness grades](docs/completeness-grades.md),
[Evidence Pack signing key custody](docs/evidence-signing-key-custody.md), the
[governed memory engine](docs/memory-engine.md) and
[reproducible evidence gates](docs/benchmarks/README.md).

The platform exposes one evidence workflow:

- **Capture**: open a Decision Envelope and bind memory, traces, policy
  decisions, prompts, tools, and human review as the action happens.
- **Reconstruct**: reproduce the point-in-time knowledge and execution path even
  when exact deterministic replay is impossible.
- **Verify**: grade every decision as Recorded, Reconstructable, Verifiable, or
  Replayable, with every missing requirement named.
- **Monitor**: when a source, policy, or model changes, identify every exposed
  decision and emit a blast-radius alert.

Memory remains a core evidence source and performance primitive. It is not the
commercial category by itself.

| | Library | Self-Hosted Server | Cloud |
|---|---|---|---|
| **Best for** | Testing, prototyping | Regulated teams, private deployments | Zero-ops production (early access) |
| **Setup** | `pip install lians-sdk[local]` | `docker compose up --build` | `pip install lians-sdk` + API key |
| **Database** | SQLite (zero setup) | Postgres 16 + pgvector | Managed |
| **Audit chain** | Yes | Yes | Yes |
| **Crypto-shred erasure** | Yes | Yes | Yes |
| **Information barriers** | Local checks | PostgreSQL RLS | Managed policy |
| **Air-gap capable** | No | Yes | No |

---

## Agent memory should improve without losing the record

Lians gives agents a durable memory loop across facts, context, decisions, outcomes,
and reviewed lessons. The Memory product keeps context current and useful; the
Records product captures behavior and oversight in an open, verifiable event format.

Most memory layers stop at storage and retrieval. Lians is built for teams that
also need to know what the agent knew, when it knew it, where the fact came from,
which outcomes followed, who was allowed to see it, and whether stale or erased
content was kept out of future context.

That is the gap between a memory demo and a memory system teams can trust in
production, especially in financial, medical, and legal environments.

### What regulated memory must prove

Generic agent memory optimizes for personalization and recall. Regulated agent
memory has a different job: it must keep the agent's context correct, current,
segregated, reproducible, and defensible under review.

Lians is designed for the failure modes that matter in institutions:

- **Stale fact contamination** - old rates, old guidance, old medication doses,
  old damages estimates, or old client facts must not silently enter context.
- **Point-in-time reconstruction** - an examiner, clinician, partner, or risk
  committee may ask what the agent knew at a specific timestamp.
- **Information barriers** - one desk, care team, or matter team must not read
  another team's memory because of an application-layer bug.
- **Erasure with audit survival** - private content must be removable without
  breaking custody records, audit hashes, or legal retention evidence.
- **Relational compliance checks** - conflicts of interest, related-party
  exposure, and referral networks are graph questions, not plain vector search.

The short competitive frame:

> Runtime vendors explain their own cloud. Lians preserves portable decision
> evidence across all of them.

### Built for regulated verticals

| Vertical | What Lians proves | Product primitives |
|---|---|---|
| **Financial institutions** | No stale or future facts influenced a decision; desk barriers held; audit state is reconstructable | Bitemporal recall, backtest contamination checks, SEC/FINRA audit export, RLS information barriers, related-party graph paths |
| **Healthcare organizations** | PHI access is scoped; care-team memory is reconstructable; patient erasure is provable | Per-subject encryption, crypto-shred certificates, HIPAA safeguard mapping, care-network graph, air-gap mode |
| **Legal institutions** | Matter walls held; privilege cutoffs are reproducible; chain-of-custody survives erasure | Matter-level barriers, `recall_at` for privilege dates, audit reconstruction, conflict-of-interest graph paths |

Procurement and technical review materials:

- [Institutional proof kit](docs/institutional-proof-kit.md)
- [Vertical pitch guide](docs/verticals.md)
- [Competitive landscape](docs/competitive-landscape.md)
- [Security whitepaper](docs/security-whitepaper.md)
- [SOC 2 / HIPAA readiness](docs/soc2-hipaa-readiness.md)
- [Threat model](docs/threat-model.md)
- [Production deploy checklist](docs/deploy.md)

---

## MCP - Native tool in any AI client

Lians is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.ebeirne%2Flians). Any MCP-compatible host - Claude Desktop, Cursor, VS Code, Windsurf, and others - can use local persistent memory immediately or connect to a hosted Lians server. No SDK code, custom adapter, Docker service, URL, or API key is required for local mode.

Your agents get eight tools automatically:

| Tool | What it does |
|------|-------------|
| `remember` | Store a fact with event time and metadata |
| `recall` | Retrieve current (non-stale) facts by semantic query |
| `recall_at` | Point-in-time recall — what did we know on date X? |
| `reconstruct` | Full audit reconstruction for regulatory submissions |
| `list_conflicts` | Surface facts where two sources disagree |
| `memory_lineage` | Full supersession history of any fact |
| `fact_history` | Time-series view of a ticker+metric (e.g. AAPL EPS) |
| `backtest_check` | Detect lookahead bias before a backtest runs |

### Claude Desktop / Cursor / Windsurf

Add to your `claude_desktop_config.json` (or equivalent MCP config):

```json
{
  "mcpServers": {
    "lians": {
      "command": "uvx",
      "args": ["--from", "lians-sdk[mcp]", "lians-mcp"]
    }
  }
}
```

Restart your client and Lians memory tools appear immediately. Local mode persists to `~/.lians/mcp.db`. To use a hosted deployment instead, set `LIANS_URL`, `LIANS_API_KEY`, and optionally `LIANS_AGENT_ID`.

### Any other MCP host

```bash
uvx --from 'lians-sdk[mcp]' lians-mcp
```

No environment variables are needed for local mode. Set `LIANS_URL`, `LIANS_API_KEY`, and optionally `LIANS_AGENT_ID` to use a remote server.

---

## Quickstart

```bash
pip install lians-sdk[local]   # SQLite plus real local semantic embeddings, no Docker
```

```python
from lians import LocalLiansClient
from datetime import datetime, timezone

mem = LocalLiansClient()

mem.add(
    agent_id="analyst-1",
    content="NVDA FY2026 revenue guidance raised to $40B",
    event_time=datetime(2025, 11, 19, 16, tzinfo=timezone.utc),
    metadata={"ticker": "NVDA", "metric": "revenue_guidance"},
)

# Superseded facts are excluded at the DB layer — never reach the LLM
results = mem.recall(agent_id="analyst-1", query="NVDA revenue guidance")

# Deeper multi-facet recall for planning and research
results = mem.recall(
    agent_id="analyst-1",
    query="What changed in the guidance and why?",
    mode="deep",
)

# Point-in-time: what did we know on March 1? (compliance-grade an