Skip to main content

Aletheia

Release Gates

Local, auditable memory for AI agents.

Aletheia is a Python package, CLI, and local service for giving agents durable memory without giving up provenance, review, privacy, or operator control. It stores memory in SQLite and treats memory as an evidence-backed lifecycle:

evidence -> candidate memory -> review/promotion -> claim -> retrieval/context -> feedback/audit

That lifecycle is the point. Raw notes, transcripts, tool observations, and LLM outputs can be captured as evidence or candidate memories, but they do not need to become trusted facts until a review or explicit active-write policy promotes them.

Aletheia is useful for local agents, agent frameworks, developer tools, research assistants, and any application that needs cross-session recall with a clear audit trail.

Status

  • Package name: aletheia-memory
  • CLI command: aletheia
  • Version: 1.6.0
  • Maturity: beta; intended for development and evaluation, not production use.
  • Runtime: Python 3.11+
  • Storage: local SQLite
  • License: MIT
  • Distribution: PyPI 1.6.0; source installs and release wheels are also supported.

1.6.0 includes the audit repairs and stricter access, privacy, and execution checks. See the 1.6.0 beta upgrade guide for compatibility changes, a fresh start with disposable data, or preserving an existing database.

What Aletheia Provides

  • Local-first memory kernel: structured evidence, candidates, claims, confidence, conflicts, projects, sessions, audit trails, and context packs.
  • Reliable retrieval: deterministic SQLite FTS search, optional governed semantic indexing, hybrid retrieval, retrieval traces, and agent-ready context budgets.
  • Review-first ingestion: ingest notes, logs, and transcripts; extract candidate memories; then promote, reject, scope, or merge after review.
  • Governed LLM memory tasks: optional LLM extraction, query expansion, entity/category suggestions, duplicate-merge suggestions, reflection drafts, and conflict explanations with provenance and review state.
  • Reasoned memory: inference candidates, reflections, semantic relations, derivation traces, lossless abstractions, and invalidation when source material changes.
  • Memory integrity controls: confidence recomputation, contradiction detection, decay policies, curation decisions, feedback, claim scoping, and audit/explanation commands.
  • Agent interfaces: in-process Python API, CLI, local HTTP API, sync/async Python SDK clients, MCP tools, and generic agent adapters.
  • Operational hardening: protected mode, scoped API tokens, namespace grants, privacy ceilings, encrypted backups, restore verification, redaction, forget tombstones, retention, integrity checks, support bundles, diagnostics, release gates, and compatibility reports.
  • Extension platform: plugin manifests, permissions, compatibility checks, conformance suites, adapters, public contracts, and generated docs/examples.

Installation

Use Python 3.11+ and install the published package:

python -m pip install aletheia-memory

Memory is independent of Desktop and Relay. Its core needs no model, account, embedding index or running external service.

For the next steps, use the packaged Python and TypeScript agent starters, then optionally tested local model recipes. These additions require Memory 1.4.0 or later. Before upgrading an existing database, follow the backup and migration guide.

Your First Reviewed Memory

In a fresh demo directory, save this as memory_demo.py and run python memory_demo.py. The example works with published 1.3.1 and with Memory 1.4.0 or later. Read the candidate and source before typing approve.

"""A deterministic evidence → review → memory example; no model required."""
import os
from pathlib import Path
from aletheia import Memory

path = Path("aletheia-demo.db")
for suffix in ("-wal", "-shm", "-journal"):
    companion = Path(str(path) + suffix)
    if companion.exists() or companion.is_symlink():
        raise SystemExit("Database companion file already exists. Preserve it and choose a new directory.")
try:
    descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
    os.close(descriptor)
except FileExistsError:
    raise SystemExit("Demo database already exists. Choose a new directory; nothing was overwritten.")

namespace = "user/demo"
memory = Memory.open(str(path), namespace=namespace)
claim_id = None
try:
    batch = memory.ingest(namespace, source_type="manual",
                          content="User prefers careful architecture notes.", trust_level="user_asserted")
    run = memory.extract_candidates(namespace, batch_id=batch.id, extractor="rule_based")
    candidates = memory.list_candidates(namespace, extraction_run_id=run.id)
    if len(candidates) != 1:
        raise SystemExit("Expected one candidate from this bounded example; inspect the extraction result.")
    candidate = candidates[0]
    print("Pending candidate:", candidate.subject, candidate.predicate, candidate.object)
    print("Source:", memory.read_event(batch.evidence_ids[0]).content)
    print("Trusted results before approval:", len(memory.retrieve(namespace, "architecture", mode="lexical")))
    try:
        approve = input("Inspect the candidate and source. Type approve to promote it: ").strip() == "approve"
    except EOFError:
        approve = False
    if approve:
        claim = memory.promote_candidate(candidate.id, reason="I inspected and approved the demo candidate.")
        claim_id = claim.id
        print(memory.context_pack(namespace, "architecture", retrieval_mode="lexical", record_usage=False).to_markdown())
        print("Provenance:", memory.explain_claim(claim.id).evidence[0]["content"])
    else:
        print("Nothing promoted. The candidate remains pending review.")
finally:
    memory.close()

if claim_id:
    reopened = Memory.open(str(path), namespace=namespace, auto_migrate=False)
    try:
        hits = reopened.retrieve(namespace, "architecture", mode="lexical")
        assert hits and hits[0].claim_id == claim_id
        print("Reopened successfully: the reviewed claim and its evidence persist.")
    finally:
        reopened.close()

Before approval there are zero trusted matches. Approval produces context, source provenance and a successful reopen check. Any other answer leaves the candidate pending. The query matches the literal word architecture; arbitrary paraphrase recall is not promised. Reruns refuse to overwrite the database.

See the complete quickstart, then the scoped HTTP agent starter. The starter generator and read-only diagnostic options require Aletheia Memory 1.4.0 or later:

aletheia examples create --type embedded --output ./memory-demo
cd memory-demo
python memory_demo.py
aletheia doctor --read-only --db ./aletheia-demo.db --namespace user/demo

On 1.3.1, use the copyable Python example above instead. The five-minute human target is not yet measured.

The remaining sections are integration/reference workflows. Trusted embedded remember() retains its active-write behavior; agents should submit candidates and leave promotion to a separate operator.

Candidate-First Ingestion

Use candidate-first ingestion when you want to capture source material without trusting every extracted statement automatically.

Ingest a note:

aletheia ingest text \
  --db ./aletheia.db \
  --namespace user/default \
  --project demo \
  --title "Agent operating notes" \
  "For architecture questions, include concrete implementation details and cite the relevant files."

Extract candidate memories:

aletheia extract run \
  --db ./aletheia.db \
  --namespace user/default \
  --batch ing_... \
  --extractor rule_based

Review candidates:

aletheia candidates list \
  --db ./aletheia.db \
  --namespace user/default

Promote only what was reviewed:

aletheia candidates promote cand_... \
  --db ./aletheia.db \
  --reason "Reviewed against the original note."

Semantic And Hybrid Retrieval

Aletheia works with deterministic lexical search out of the box. You can also index promoted claims with a local semantic provider and run hybrid retrieval:

aletheia index semantic \
  --db ./aletheia.db \
  --namespace user/default \
  --target claims \
  --provider local_hash \
  --dimension 64

aletheia search \
  --db ./aletheia.db \
  --namespace user/default \
  --mode hybrid \
  --semantic-provider local_hash \
  "What response style does the user prefer?"

Python API

Use the in-process kernel when your Python application can safely share the local SQLite database.

from aletheia import Memory

memory = Memory.open("./aletheia.db", namespace="user/default")

try:
    claim = memory.remember(
        namespace="user/default",
        memory_type="preference",
        subject="user",
        predicate="prefers_response_style",
        object="practical and direct",
    )

    results = memory.retrieve(
        namespace="user/default",
        query="response style",
        mode="lexical",
        limit=5,
    )

    pack = memory.context_pack(
        namespace="user/default",
        query="How should the assistant respond?",
        retrieval_mode="lexical",
        token_budget=1200,
    )

    print(claim.id)
    print([result.claim_id for result in results])
    print(pack.to_markdown())
finally:
    memory.close()

Local HTTP Service

Use the HTTP service when another process, runtime, or language needs access to memory.

Create an API client and scoped token:

aletheia clients create \
  --db ./aletheia.db \
  --name local-agent \
  --type agent

aletheia auth create-token \
  --db ./aletheia.db \
  --client local-agent \
  --namespace user/default \
  --capabilities memory:read,memory:context,memory:write_candidate,memory:feedback,memory:audit

Start the local daemon:

aletheia serve \
  --db ./aletheia.db \
  --host 127.0.0.1 \
  --port 8765

Health and API discovery:

curl -s http://127.0.0.1:8765/v1/health
curl -s http://127.0.0.1:8765/v1/openapi.json

Fetch a context pack:

curl -s http://127.0.0.1:8765/v1/context-pack \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer atl_..." \
  -d '{
    "namespace": "user/default",
    "query": "How should the assistant respond?",
    "retrieval_mode": "lexical",
    "token_budget": 1200,
    "record_usage": true
  }'

Store an agent observation as a reviewable candidate:

curl -s http://127.0.0.1:8765/v1/remember \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer atl_..." \
  -H "Idempotency-Key: task-001-memory-001" \
  -d '{
    "namespace": "user/default",
    "write_mode": "candidate",
    "memory_type": "preference",
    "subject": "user",
    "predicate": "prefers_response_style",
    "object": "practical and direct",
    "evidence_text": "The user asked for practical and direct answers."
  }'

MCP

Use MCP when an agent host can run local stdio tools.

aletheia mcp \
  --db ./aletheia.db \
  --namespace user/default \
  --mode read_write_candidate

Recommended modes:

  • read_only for context-only consumers.
  • read_write_candidate for normal local agents.
  • read_write_active for trusted tools that may write active claims.
  • admin for operational tooling.

Common Workflows

Inspect claim provenance:

aletheia audit clm_... --db ./aletheia.db

Record feedback:

aletheia feedback clm_... \
  --db ./aletheia.db \
  --namespace user/default \
  --signal confirmed \
  --note "Confirmed during review."

Detect and resolve conflicts:

aletheia conflicts list \
  --db ./aletheia.db \
  --namespace user/default

aletheia conflicts resolve conf_... \
  --db ./aletheia.db \
  --strategy context_scope \
  --note "Both claims are valid in different contexts."

Run operational checks:

aletheia doctor --db ./aletheia.db
aletheia compatibility report --db ./aletheia.db
aletheia readiness check --db ./aletheia.db --namespace user/default

Create and verify an encrypted backup:

aletheia backup create \
  --db ./aletheia.db \
  --namespace user/default \
  --output ./aletheia.alet \
  --encrypt \
  --passphrase "change-me"

aletheia backup verify ./aletheia.alet \
  --db ./aletheia.db \
  --passphrase "change-me"

Generate local docs:

aletheia docs build --db ./aletheia.db --output ./site
aletheia examples list --db ./aletheia.db

Documentation

Aletheia ships its docs with the installed package:

aletheia docs list
aletheia docs path
aletheia docs show index

Recommended starting points:

Trust And Privacy Model

Aletheia is local-first by default. Evidence, claims, review state, service logs, metrics, traces, and operational records live in the configured SQLite database unless explicitly exported.

Important boundaries:

  • Raw ingested content is evidence, not truth.
  • Candidate writes are the default safer write path for agents.
  • Active writes require explicit authority.
  • API tokens can be scoped by capability, namespace grant, and privacy ceiling.
  • Protected mode encrypts sensitive stored content when configured with local key material.
  • External LLM providers are optional and governed by policy.
  • Forget and redaction workflows preserve tombstones and auditability.

Development

Run tests:

uv run --extra dev pytest

Run the release gate for the public baseline:

python scripts/release_gate.py --branch main

Build the package:

uv build

Release Verification

Before cutting a release, run:

uv run --extra dev pytest
python scripts/release_gate.py --branch main
uv build

Community And Security

Contributing

Contributions should preserve Aletheia's core boundaries: local-first operation, evidence-backed memory, candidate-first agent writes, explicit review for trust, scoped access, and auditability. Open an issue or discussion before introducing new persistent schema, new network behavior, or new active-write paths.

Development Installation

For repository development after the public quickstart:

git clone https://github.com/khaledgabal2/aletheia-memory.git
cd aletheia-memory
python -m pip install -e ".[dev]"
python -m pytest

A reviewed wheel can instead be installed by its local path. Development checkouts may contain unreleased changes; use a pinned published version for repeatable evaluation. All releases so far are beta. Never commit credentials or private databases.

Local Application Pairing

Since 1.5.0, Memory automatically advertises POSIX loopback services and supports owner-approved, scoped pairing over a persistent local TLS identity. Use aletheia pairing invite --help to create a five-minute code. Discovery alone never authorizes access. See the local pairing protocol for grants, opt-out, lifecycle, supported platforms, and recovery.

Metadata

Release files for aletheia-memory 1.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aletheia-memory 1.6.0
File Size Uploaded Provenance Actions
aletheia_memory-1.6.0.tar.gz 934.5 kB With provenance Details for aletheia_memory-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aletheia-memory 1.6.0
File Interpreter ABI Platform Actions
aletheia_memory-1.6.0-py3-none-any.whl Python 3 none any Details for aletheia_memory-1.6.0-py3-none-any.whl

Total release size: 1.7 MB

Release files / aletheia_memory-1.6.0.tar.gz

Download URL aletheia_memory-1.6.0.tar.gz
Size 934.5 kB
Tags Source
SHA-256 checksum
How to use checksums
75d3c04c657c30e75e73e03ff04fad06fa56ac6bb19e8b4e13a279fa0cf5a1ec
BLAKE2b-256 checksum
How to use checksums
66cae173add18c8e13ec0046ade5c7f6f1b2410fa78b387182c0d6af469a171c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.

Transparency log

Release files / aletheia_memory-1.6.0-py3-none-any.whl

Download URL aletheia_memory-1.6.0-py3-none-any.whl
Size 789.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f86580b52e353751d778474581c04c377da0459ce6157208203ea805aad24f2a
BLAKE2b-256 checksum
How to use checksums
96f7bdefbea4256dba39c5bac504e4d19dcb688a865e1eca5daebdb67bbeeb16
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.

Transparency log

Security for aletheia-memory 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aletheia_memory-1.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page