Aletheia

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
• Current version: 1.3.1
• Runtime: Python 3.11+
• Storage: local SQLite
• License: MIT
• Distribution: GitHub/source install and wheel builds are supported today; pip install aletheia-memory becomes the primary path after PyPI publication.

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

Install directly from the public GitHub repository:

python -m pip install "git+https://github.com/khaledgabal2/aletheia-memory.git"

After the PyPI package is published, install from the package index:

python -m pip install aletheia-memory

Or install a release wheel:

python -m pip install ./dist/aletheia_memory-1.3.1-py3-none-any.whl

Verify the CLI and bundled docs:

aletheia --help
aletheia docs list
aletheia docs show introduction

Install from source:

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

For local development with uv:

uv run --extra dev aletheia --help
uv run --extra dev pytest

Quick Start

Create a local SQLite database:

aletheia init --db ./aletheia.db

Store a reviewed explicit memory:

aletheia remember \
  --db ./aletheia.db \
  --namespace user/default \
  --type preference \
  --subject user \
  --predicate prefers_response_style \
  --object "practical and direct"

Search memory:

aletheia search \
  --db ./aletheia.db \
  --namespace user/default \
  "response style"

Build an agent-ready context pack:

aletheia context-pack \
  --db ./aletheia.db \
  --namespace user/default \
  --mode lexical \
  --token-budget 1200 \
  "How should the assistant respond?"

During repository development, prefix the same commands with uv run --extra dev:

uv run --extra dev aletheia init --db ./aletheia.db

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:

• Installation
• Introduction
• Core Concepts
• Memory Lifecycle
• Architecture
• Interfaces
• CLI Reference
• Integration Guide
• HTTP API Reference
• MCP Reference
• Security And Privacy Guide
• Operations Guide
• Troubleshooting
• Near-Future Changes

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

• Contributions: CONTRIBUTING.md
• Security reports: SECURITY.md
• Release notes: CHANGELOG.md

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.