Lians Agent Memory

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, the normative completeness grades, Evidence Pack signing key custody, the governed memory engine and reproducible evidence gates.

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.

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

Procurement and technical review materials:

• Institutional proof kit

• Vertical pitch guide

• Competitive landscape

• Security whitepaper

• SOC 2 / HIPAA readiness

• Threat model

• Production deploy checklist

Related MCP server: cogmem

MCP - Native tool in any AI client

Lians is listed on the official MCP Registry. 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:

Claude Desktop / Cursor / Windsurf

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

{
  "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

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

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

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 answer)
results = mem.recall_at(
    agent_id="analyst-1",
    query="NVDA revenue guidance",
    as_of=datetime(2025, 3, 1, tzinfo=timezone.utc),
)

# Every result includes receipt_sha256, provenance_coverage, and the
# resolved serving mode and latency budget.

Switch to the hosted server with one line: from lians import LiansClient as LocalLiansClient

Decision evidence quickstart

from datetime import datetime, timezone
from lians import AsyncLiansClient

async with AsyncLiansClient(base_url=LIANS_URL, api_key=LIANS_API_KEY) as lians:
    envelope = await lians.open_decision_envelope(
        agent_id="underwriter-1",
        decision_type="credit_application",
        regime="ECOA_REG_B",
        completeness_profile="regulated_recordkeeping",
        knowledge_as_of=datetime.now(timezone.utc),
    )

    context = await lians.recall(
        agent_id="underwriter-1",
        query="verified applicant income",
        decision_envelope_id=envelope["id"],
    )

    sealed = await lians.seal_decision_envelope(
        envelope["id"],
        outcome="manual_review",
        decided_at=datetime.now(timezone.utc),
        input_hash=INPUT_SHA256,
        output_hash=OUTPUT_SHA256,
    )

    # No overclaiming: every missing requirement names the grade it blocks.
    print(sealed["completeness"])

Agent harness — drop-in memory loop

LiansMemoryHarness wraps the two operations every memory-augmented agent needs — recall-before and remember-after — into one object, with the compliance scoping (subject, source, event-time, information barrier) regulated deployments require. Works with any sync client (LiansClient or LocalLiansClient) and any model.

from lians import LiansClient, LiansMemoryHarness

harness = LiansMemoryHarness(mem, agent_id="research-desk", domain="finance")

# One call: recall context, run your model, persist the response.
answer = harness.run_turn(
    "What is NVDA's current revenue guidance?",
    generate=lambda context, query: call_model(f"{context}\n\nUser: {query}"),
)

# Or control each step:
context = harness.recall_context("NVDA revenue guidance")   # ready to inject
harness.remember("Desk note: guidance now $40B")            # write after the turn

Regulated scoping ties every write to one data subject and an information barrier:

harness = LiansMemoryHarness(
    mem, agent_id="care-team-3",
    subject_id="MRN-00042",       # per-subject key — the crypto-shred target
    barrier_group="oncology",     # information-barrier tag
    domain="healthcare",
)

Runnable end-to-end demo: agentmem/examples/harness_demo.py.

Relationship graph — compliance questions that are inherently relational

Some compliance checks are graph queries. Lians stores bitemporal relationship edges alongside facts — same audit chain, same information barriers, no graph database — so you can answer them point-in-time:

• Legal — conflict-of-interest reachability (ABA 1.7/1.9): is an attorney connected to an adverse party?

• Finance — related-party / beneficial-ownership (SEC, AML/KYC): is a counterparty within N hops of a restricted entity?

• Healthcare — care-network / referral-pattern (anti-kickback) analysis.

mem.relate("analyst-1", src_entity="Attorney", rel_type="represented",
           dst_entity="ClientX", event_time=datetime(2026, 1, 1, tzinfo=timezone.utc))
mem.relate("analyst-1", src_entity="ClientX", rel_type="adverse_to",
           dst_entity="PartyY", event_time=datetime(2026, 1, 1, tzinfo=timezone.utc))

# Conflict-of-interest check — is there a connection, and through what?
path = mem.path("analyst-1", src_entity="Attorney", dst_entity="PartyY")
# → {"connected": True, "hops": 2, "path": [...]}

# Point-in-time: who was connected on the day of the trade?
mem.neighbors("analyst-1", entity="FundA", depth=2, as_of=datetime(2025, 6, 1, tzinfo=timezone.utc))

# Graph-proximity reranking — boost recalls about entities near an anchor
mem.recall_near("analyst-1", query="earnings", near_entity="FundA", near_key="ticker")

Endpoints: POST /v1/graph/relate · /v1/graph/unrelate · /v1/graph/extract (text → edges, rule-based or opt-in LLM) · GET /v1/graph/neighbors · /v1/graph/path (all as_of-capable). Inspired by Zep/Graphiti, built on our compliance spine.

Agent integrations — Claude Code, Codex, MCP

Give any coding agent persistent, compliance-grade memory:

Why Lians

Institutional AI agents accumulate facts that change over time: rate decisions supersede prior ones, guidance gets revised, medication doses change, care plans evolve, damages estimates move, and matter facts are corrected during discovery. Systems that return every version with equal rank contaminate the LLM context with stale facts.

Lians fixes this with a bitemporal model:

• event_time — when the fact happened (business time)

• valid_from / valid_to — when it was known (system time)

Superseded facts are excluded at the database layer. Every write is recorded in a tamper-evident SHA-256 hash chain; physical immutability and SEC 17a-4 deployment claims require separately configured WORM storage and policy controls. Per-subject keys can be destroyed for governed erasure while the audit trail survives. Information barriers are enforced at PostgreSQL RLS, not only at the application layer.

How Lians compares

Temporal memory is no longer unique: Graphiti documents a bitemporal knowledge graph, Mem0 documents temporal reasoning and history, Hindsight documents query-time temporal recall and audit controls, and Supermemory documents content versioning and a temporal graph. Lians should be evaluated on the compound decision-evidence boundary it implements:

• reconstruct a named decision at both event-time and knowledge-time cutoffs;

• enumerate the source versions included and excluded at those cutoffs;

• detect post-cutoff leakage before a result is accepted;

• emit a content-addressed Evidence Pack that can be verified offline; and

• preserve the surrounding chain when subject content is crypto-erased.

The repository's regulated-memory harness is useful product evidence, not an independent general-product leaderboard. Current leadership language remains gated on production load, isolation, restore, failure-injection, public benchmark, and independent-reproduction evidence. See docs/competitive-landscape.md and the runnable claim policy in agentmem/benchmarks/release_claims.py.

→ Lookahead-bias demo — the same agent backtest with naive vs point-in-time retrieval (Sharpe 4.6 vs −0.6, every leak logged): ebeirne/lookahead-bias-demo · in-repo → Full benchmark numbers: docs/benchmark.md → Regulated-eval head-to-head (five compliance invariants, Lians 5.0 / Zep–Graphiti 2.0 / mem0 0.5): docs/regulated-eval-results.md — Lians, Graphiti OSS, and mem0 OSS all executed live in their default configurations (per-cell evidence in the appendix); remaining columns scored from their public API surface via runnable adapters you can re-run with keys.

Language SDKs

Lians maintains client implementations across five languages. Public package versions currently differ by ecosystem; use the explicit coordinates below and verify the machine-readable published release status.

→ One-page install + 30-second quickstart for every language: docs/install.md

All five cover core memory operations. Python and TypeScript currently expose a broader advanced surface than Go, Java, and C; verify the client you plan to use against the OpenAPI contract before a pilot.

Framework integrations

Self-hosted quickstart

git clone https://github.com/Lians-ai/Lians.git && cd Lians/agentmem
cp .env.demo .env
docker compose up --build -d
python scripts/seed_demo.py   # prints a demo API key; open demo/index.html

Deploy to Fly.io, Kubernetes, or bare Docker: docs/deploy.md

SDK reference

# All three clients share the same API surface
from lians import LiansClient          # sync, connects to hosted/self-hosted server
from lians import AsyncLiansClient     # async, for FastAPI / async frameworks
from lians import LocalLiansClient     # local SQLite, no server needed

client.add(agent_id, content, event_time, metadata={}, importance=0.5)
client.add_from_messages(agent_id, messages=[{"role": "user", "content": "..."}])
client.recall(agent_id, query, k=5)
client.recall_at(agent_id, query, as_of=datetime(...))   # point-in-time
client.snapshot(agent_id, as_of=datetime(...))           # full state export
client.backtest_check(agent_id, simulation_as_of=...)    # lookahead-bias detection
client.erase(subject_id, request_ref)                    # GDPR crypto-shred

Architecture

                    ┌──────────────┐
                    │  LLM / Agent │
                    └──────┬───────┘
                           │  REST / MCP
               ┌───────────▼────────────┐
               │        Lians API        │   FastAPI · rate-limit · OTEL
               └──┬────────────────┬────┘
          ┌───────▼──────┐  ┌──────▼───────┐
          │   memories    │  │  event_log   │
          │  (encrypted)  │  │ (hash chain) │
          │  bitemporal   │  │  append-only │
          └───────┬───────┘  └──────────────┘
                  │
          ┌───────▼───────┐
          │  subject_keys  │   AES-256-GCM per subject
          │  (crypto-shred)│   destroy key = content unrecoverable
          └───────────────┘

  Postgres 16 + pgvector (HNSW)      Redis (recall hot cache)

Recall pipeline: BM25 + cosine (Voyage Finance-2) → recency decay → validity gate (valid_to IS NULL for present; valid_from ≤ as_of < valid_to for point-in-time)

Supersession pipeline: Stage 1 (metadata key overlap) → Stage 2 (deterministic: SUPERSEDES / CONFIRMS / ADDS) → Stage 3 (optional LLM adjudication for paraphrase detection)

Configuration

Full reference: agentmem/.env.example

Key endpoints

Interactive docs: http://localhost:8000/docs

Running tests

pip install -e ".[dev]"
python scripts/test_all.py

# Benchmarks only (no API keys required)
PYTHONPATH=agentmem/src python -m pytest \
  agentmem/tests/test_supersession_benchmark.py \
  agentmem/tests/test_recall_quality.py -v

See docs/testing.md for the six named invariants (temporal soundness, audit immutability, erasure, etc.).

Production & operations

Built to run in a regulated production environment, not just to demo:

• Exactly-once writes — Idempotency-Key on POST /v1/memories; the SDKs send a stable key automatically, so a retried write never duplicates.

• Resilient clients — built-in retry with exponential backoff on transport errors / 5xx / 429.

• Kubernetes probes — cheap /livez (liveness) and deep /readyz (readiness), so a dependency blip doesn't restart healthy pods.

• Rate limiting — per-API-key sliding window (Redis), fails open.

• Access control — namespace-scoped keys, read/write/admin scopes, RBAC roles (owner/analyst/compliance/readonly), and SSO via gateway forward-auth.

• DB-layer information barriers — RESTRICTIVE PostgreSQL RLS, proven in CI against a non-superuser role. Run the app as a non-superuser DB role — superusers bypass RLS.

• Memory admission control — govern what's allowed into memory: PII/PHI/MNPI detection, source-trust, prompt-injection quarantine, and a high-risk review queue (ADMISSION_MODE). No other memory layer does this.

• SIEM streaming — every audit event forwarded to Splunk HEC / Datadog / Elastic (SIEM_URL), fire-and-forget.

• Observability — Prometheus metrics + Grafana, OpenTelemetry traces, JSON access logs with a request ID.

• Evaluation — a judge-free memory-eval harness (agentmem/benchmarks/memory_eval.py) in the LoCoMo/LongMemEval shape.

Security & procurement docs: security-whitepaper.md · threat-model.md · soc2-hipaa-readiness.md · sso.md · publishing.md

Compliance

Scope of these claims: Lians provides the technical controls mapped above — it is software, not a certification. Regulatory compliance is a property of your deployment and organization (retention configuration, policies, attestations such as SOC 2 or a HIPAA assessment), and several controls require operator configuration (WORM object-lock, non-superuser DB role, KMS). Every claim links to the doc that says exactly what is and isn't covered — start with soc2-hipaa-readiness.md.

Full documentation: compliance.md · hipaa.md · security-whitepaper.md · threat-model.md · soc2-hipaa-readiness.md · sso.md · worm-storage.md

Access control: namespace-scoped API keys with read/write/admin scopes and RBAC roles (owner/analyst/compliance/readonly); SSO via gateway forward-auth (any OIDC/SAML IdP).

Packaging & Pricing

Lians is open-source and fully self-hostable — the entire feature set, including every compliance primitive, is in this repository under Apache 2.0. Paid packages sell deployment support, hardening review, and evidence packets around the open core, not license keys. A managed cloud is in early access for customers whose compliance posture allows hosted processing (contact us); regulated buyers should choose the package by deployment boundary and evidence requirements, not by a consumer-style monthly tier.

Healthcare customers require an executed BAA before PHI is processed in a managed environment. Financial and legal customers may require customer-managed keys, private networking, regional residency, dedicated environments, or air-gapped deployment.

Full packaging documentation: docs/pricing-tiers.md and docs/billing.md

Switching from another system? Migrate from mem0 or Migrate from Zep CE

License

Apache 2.0 — see LICENSE.