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.
For properties that can hold several values, Aletheia supports
explicit predicate cardinality:
memory.set_predicate_semantics("likes", cardinality="multiple"). Distinct set
members then coexist in ordinary recall. Undeclared predicates keep exclusive,
single-value conflict handling. Configure through the embedded API,
HTTP/Python SDKs, or
CLI.
Status
- Package name:
aletheia-memory - CLI command:
aletheia - Latest release: GitHub and PyPI.
- Version: 1.8.0; production/stable within the qualified support boundaries.
- API: v1; storage: 1.3.1. Earlier 1.6.x releases retain their beta status.
- Runtime: Python 3.11+
- Storage: local SQLite
- License: MIT
- Distribution: PyPI; source installs and release wheels are also supported.
1.8.0 adds explicit predicate cardinality across Python, HTTP, CLI and SDKs, with authorization and conflict-management fixes. Multivalued properties coexist; single-valued contradictions remain disputed. Read the release notes, upgrade guide and qualification record before upgrading. Existing databases require an additive schema migration even though the storage marker remains 1.3.1. Model output still requires human review; local pairing remains POSIX-only and Windows ACL support assumes trusted ancestors.
1.6.2 fixes HTTP semantic provider selection and reports lexical fallback accurately.
Select the server provider explicitly with ALETHEIA_SEMANTIC_PROVIDER=ollama_style
and keep its model, dimensions and prefixes consistent with the index. See the
1.6.2 upgrade guide
and release verification.
1.6.1 was published on October 13, 2026 and adds repairs from the independent 1.6.0 review. See the review resolution and 1.6.1 upgrade guide.
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. The server supports the JSON-RPC initialize/initialized handshake, tool discovery, tool calls, and ping over newline-delimited stdio. Protocol versions 2025-06-18 and 2024-11-05 are supported. The selected namespace also applies to tokenless local sessions.
aletheia mcp \
--db ./aletheia.db \
--namespace user/default \
--mode read_write_candidate
Recommended modes:
read_onlyfor context-only consumers.read_write_candidatefor normal local agents.read_write_activefor trusted tools that may write active claims.adminfor 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 \
--scoped-json '[{"claim_id":"clm_first","scope_type":"contextual","applies_when":"progress updates"},{"claim_id":"clm_second","scope_type":"contextual","applies_when":"architecture design"}]' \
--note "Both claims are valid in different contexts."
Replace both claim IDs with every member of the conflict family. Context and time resolutions require complete scopes in the same operation; invalid or missing scopes leave the conflict unresolved. Temporal scopes require at least one time boundary, with the start before the end when both are supplied.
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.
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 deployment. Version 1.8.0 is production/stable within its documented support boundaries; releases before 1.7.0 remain 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.8.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aletheia_memory-1.8.0.tar.gz | 1.1 MB | With provenance | Details for aletheia_memory-1.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aletheia_memory-1.8.0-py3-none-any.whl | Python 3 | none | any | Details for aletheia_memory-1.8.0-py3-none-any.whl |
Total release size: 2.0 MB
Release files / aletheia_memory-1.8.0.tar.gz
| Download URL | aletheia_memory-1.8.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5b18fe6f4b1cc0b5532d2490da222e3f29584487f77c42037797a4f9dc6b4db8
|
|
BLAKE2b-256 checksum How to use checksums |
903f312f4986cbfbfde468dc411004465cc85d3e5ac94542ec27fad6abf6c56f
|
| 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 Oct 18, 2026.
Transparency logRelease files / aletheia_memory-1.8.0-py3-none-any.whl
| Download URL | aletheia_memory-1.8.0-py3-none-any.whl |
|---|---|
| Size | 905.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
88cd752e40807c118eced4399be9641fabd497694abe842355c4986812e6da7a
|
|
BLAKE2b-256 checksum How to use checksums |
27d626db6ccbbdbee4fb3ad52d8511e6e9e4226009b0845a592770645a65068f
|
| 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 Oct 18, 2026.
Transparency logSecurity for aletheia-memory 1.8.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.
Attestation for aletheia_memory-1.8.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 Oct 18, 2026.
Transparency logA 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.