meta-agents-db

Agent-native database with causal memory, composite-scored recall, and a tamper-evident integrity chain.

The first database designed for autonomous AI agents.

Install

pip install meta-agents-db

Quick start

from meta_agents_db import MetaAgentsDB
from tempfile import TemporaryDirectory

with TemporaryDirectory() as directory:
    db = MetaAgentsDB(directory, embedding="none")
    evidence = db.write(tenant_id="example", content="ORBIT calibration evidence",
                        tags=["domain:research"])
    decision = db.write(tenant_id="example",
                        payload={"content": "ORBIT calibration decision", "approved": True},
                        caused_by=[evidence])
    results = db.recall("ORBIT calibration", tenant_id="example", top_k=10)
    chain = db.trace_cause(decision, tenant_id="example", direction="backward")
    assert results and any(edge["to"] == evidence for edge in chain)
    del db  # Release the store owner before reopening or removing its directory.

Python input contract

tenant_id is required for writes and recall. Never infer it from a domain. write(content="text", tenant_id=...) stores {"content": "text"}. Alternatively, payload= accepts a dict, list, dataclass instance, or an existing JSON string. Dict/list/dataclass inputs are deterministically serialized with sorted keys and compact separators. Nested values must be JSON-compatible; NaN, infinity, arbitrary objects, cycles, and unsupported keys fail rather than being stringified silently. Do not supply both content and payload. For unencoded plain text, use content, not payload.

MetaAgentsDB.valid_scopes() lists user, workspace, org, and public_template. These are visibility primitives, NOT application domains. Use extensible tags such as domain:market or payload={"domain": "research"} for application namespaces. MetaAgentsDB.valid_memory_types() lists the supported lifecycle types: ephemeral, session, long_term, artifact, summary, and hypothesis. Invalid values list the valid alternatives.

Offline operation and capabilities

Set MADB_OFFLINE=1 before initialization to disable remote model acquisition. This conservative mode disables embeddings even if model files are cached; explicit embedding="candle" conflicts with offline mode and fails clearly. db.capabilities() reports semantic/tag/causal retrieval availability, the embedding initialization state, actual vector-index strategy, and degraded mode. Lexical/tag/recency/causal retrieval remains available offline. This is not a guarantee of semantic-equivalent quality. Normal auto mode retains graceful fallback when model initialization fails. embedding="none" disables embeddings for an individual database without setting the process-wide policy.

The MCP server also honors MADB_OFFLINE=1: update checks and telemetry are disabled before module initialization. Offline installation requires the full RC wheelhouse, not just the two MADB wheels:

python -m pip install --no-index --find-links ./wheelhouse madb-mcp-server
MADB_OFFLINE=1 MADB_TENANT_ID=example MADB_DATA_DIR=./test-data madb-mcp-server

Features

• Causal DAG — every memory links to its causes; trace full decision chains
• 5-signal composite recall — vector similarity + recency + causal proximity + importance + tag overlap
• Storage-layer policy (roadmap) — risk, budget, and rate caps at write time; the policy engine is not enabled by default in this release
• Optional HNSW vector index — approximate nearest-neighbor search (opt-in; brute-force is the default backend)
• Session caching — deduplicates repeated recalls within a pipeline cycle
• MVCC — snapshot isolation for concurrent readers/writers
• WAL + SSTables — crash-safe append-only log with background compaction

License

Meta-Agents.AI Proprietary License v1.0. Install-and-use is permitted for end-users of the published wheels; source access, OEM embedding, and hosted-service rights are reserved for separately-negotiated agreements. Patent pending.