lunaris

PyO3 0.26 Python bindings for the Lunaris agent memory engine.

Installation

From source (development):

cd crates/lunaris-py
uv venv --python 3.11 .venv
source .venv/bin/activate
uv pip install maturin
maturin develop --release

A PyPI wheel will ship with the v0.1.1 release via the Plan 08-04 multi-platform prebuild matrix.

For the full user-facing install + quickstart guide covering both Python and TypeScript, see docs/bindings.md.

Requirements

• Python 3.11+ (abi3 stable ABI — one wheel covers 3.11, 3.12, 3.13)
• A Moon backend reachable from the process. moon:// is the only supported URL scheme — postgres:// and sqlite:// were removed in 0.7.0 and now return UnsupportedScheme. See docs/migration/0.6-to-0.7.md.

Example

import asyncio
import lunaris

async def main():
    handle = await lunaris.open("moon://127.0.0.1:6380")
    lsn = await handle.ingest({
        "id": "01JABCDEFGHJKMNPQRSTVWXYZ0",
        "scope": "_dev_",
        "source": "py-example",
        "content": "Lunaris bi-temporal hello.",
        "metadata": {},
        "t_ref": None,
        "bt": {"valid": [{"wall_ms": 0, "counter": 0, "node_id": 0}, None],
               "sys":   [{"wall_ms": 0, "counter": 0, "node_id": 0}, None]},
    })
    print("ingested at", lsn)

    hits = await handle.recall().query("bi-temporal hello").top(5).execute()
    for h in hits:
        print(h)

asyncio.run(main())

Custom embedder + reranker

The default embedder is granite-embedding-311m-multilingual-r2 (768-d), served from a Q4_K_M GGUF in-process via llama.cpp — no Ollama, no external service required. Stage the GGUF at ~/.lunaris/models/ (the MCP server does this lazily; other deployments download out-of-band). An air-gapped Ollama HTTP embedder remains available as an operator escape hatch behind --features embed-remote.

The EmbedderConfig and RerankerConfig factories swap the backend at handle-construction time; the env-driven default remains in place for callers that don't pass one.

import asyncio
import lunaris
from lunaris import EmbedderConfig, RerankerConfig

async def main():
    mem = await lunaris.open(
        "moon://127.0.0.1:6380",
        embedder=EmbedderConfig.llamacpp(),   # granite-r2 Q4_K_M GGUF, in-process llama.cpp
        reranker=RerankerConfig.llamacpp(),   # bge-reranker-v2-m3 Q5_K_M GGUF cross-encoder
    )
    # ... ingest / recall as usual

asyncio.run(main())

See docs/sdk/embedder-config.md for the full customization guide — in-process llama.cpp, noop, and the operator Ollama escape hatch — with troubleshooting and the FFI-cliff limits.

Surface parity

The Python class / method surface is generated from crates/lunaris-codegen/annotations/surface.toml (Plan 08-01). The parity-check CI job fails any PR that drifts the committed snapshot from the regenerated output — pip install lunaris never lags the Rust crate.

Three-surface pipeline toggles

The GraphPipeline and ConsolidatorPipeline default to OFF (blueprint §5.1 / §5.2). Flip them at any of three surfaces:

Resolution order: code > env > config — code is always authoritative.