Skip to content

liel documentation

liel is a single-file, portable external brain for local AI tools, agents, and Python workflows.

It stores facts, decisions, tasks, files, sources, tool results, and their relationships in one portable .liel file. The core package has no required runtime dependencies and does not need an external database server, cloud service, or background daemon.

Under the hood, liel uses a Rust-core property graph storage engine with Python bindings and optional MCP integration.

If you are new to the project, start with Why liel. It explains the problem liel is designed for: durable AI memory that keeps relationships, not just retrieved text.

Reading paths

The docs are split by audience, not by importance:

Audience Start here What belongs there
End users trying the package Quickstart Install, demo, first Python and MCP paths
Users comparing or merging files Command line liel version, liel diff, and liel merge
Python application users Python API Runtime API, exceptions, transactions, performance notes
AI-tool integrators MCP guide and AI memory playbook Tool setup and operating rules
Teams sharing .liel files Conventions Recommended labels and canonicalization habits
Connector / format authors Format spec Byte layout and compatibility invariants
CI, dashboards, and ecosystem tools Machine-readable surfaces and Viewer JSON contract Which JSON contract to use; no raw .liel in the browser as the primary path
Contributors and reviewers Architecture and Product trade-offs System shape and design rationale

Curious first-time reader

Read Why liel, then skim product trade-offs. This path explains the memory problem, the single-file shape, and the deliberate limits before you read APIs.

Trying it from Python

Start with the README, then read the Quickstart and Python API. It covers the API rooted at liel.open(), exceptions, transactions, the QueryBuilder, and operational guidance for scans and bulk export.

Connecting an AI agent such as Claude

Use the MCP server. Enable it with pip install "liel[mcp]" and start it with liel-mcp --path my.liel. The official MCP surface is fixed to ten tools: liel_overview, liel_find, liel_explore, liel_trace, liel_map, liel_diff, liel_merge_preview, liel_manifest, liel_append, and liel_merge. The exposed tools are documented in the Tools reference, and practical agent behavior lives in the AI memory playbook.

Contributing code

Read CONTRIBUTING.md, then use architecture overview for module shape and product trade-offs for scope boundaries.

Understanding the file format

The format spec is the canonical file-layout reference. Read it with product trade-offs ยง6 when you need both byte layout and rationale.

Building a connector or ecosystem tool in another language

Start with format spec for byte layout, Python API for behavior exposed to users, and reliability for commit and recovery semantics.

Want a quick overview

Site structure

Section Audience
Why liel New users deciding whether this solves their AI memory problem
Guide Application and tool users using Python or MCP
Samples Sample viewer, examples/ Python scripts, and repo demos
Conventions Teams and tools sharing .liel files
Reference Users and connector authors checking behavior and file compatibility
Design Anyone reviewing architecture, scope, and trade-offs
Primary sources of truth:

Repository

github.com/hy-token/liel