Metadata-Version: 2.4
Name: meta-agents-db
Version: 0.2.15
Classifier: Development Status :: 3 - Alpha
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
License-File: LICENSE
Summary: Agent-native database with causal memory, composite-scored recall, and a tamper-evident integrity chain
Keywords: database,agents,memory,ai,mcp,causal,vector,recall
Author-email: Pushkar Singh <01@meta-agents.ai>, Pushkar Singh <spshkar84@gmail.com>, Pushkar Singh <spshkar84@meta-agents.ai>
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://meta-agents.ai/docs
Project-URL: Homepage, https://meta-agents.ai

# 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

```bash
pip install meta-agents-db
```

## Quick start

```python
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:

```bash
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](https://github.com/spshkar84/meta-agents-db/blob/main/LICENSE). 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.

