Metadata-Version: 2.4
Name: matriosha
Version: 2.0.2
Summary: Matriosha is a Python CLI for an encrypted, auditable AI context engine.
Project-URL: Homepage, https://matriosha.in
Project-URL: Repository, https://github.com/drizzoai-afk/matriosha
Project-URL: Issues, https://github.com/drizzoai-afk/matriosha/issues
Author: Daniele Vincenzo Rizzo
License: BSD 3-Clause License
        
        Copyright (c) 2026, Matriosha contributors
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software without
           specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
        ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
        INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON
        ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
        INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS
        SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: ai,auditability,cli,context-engine,encryption,memory
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.11
Requires-Dist: argon2-cffi<24,>=23.1
Requires-Dist: certifi>=2023.7.22
Requires-Dist: click<8.2,>=8.1
Requires-Dist: cryptography<43,>=42
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: fastembed<1,>=0.3
Requires-Dist: google-cloud-secret-manager<3,>=2.16
Requires-Dist: httpx<0.28,>=0.27
Requires-Dist: jax>=0.4.20
Requires-Dist: keyring<26,>=25
Requires-Dist: openpyxl<4,>=3.1
Requires-Dist: pillow<12,>=10.3
Requires-Dist: platformdirs<5,>=4.2
Requires-Dist: portalocker<3,>=2.8
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pynacl<2,>=1.5
Requires-Dist: pypdf<6,>=4.2
Requires-Dist: pytesseract<0.4,>=0.3.10
Requires-Dist: python-docx<2,>=1.1
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: qrcode[pil]<8,>=7.4.2
Requires-Dist: requests<3,>=2.32
Requires-Dist: rich<14,>=13.7
Requires-Dist: stripe<9.0.0,>=8.0.0
Requires-Dist: supabase<3,>=2.5
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: typer<0.21,>=0.20
Requires-Dist: uvicorn[standard]<1,>=0.28
Provides-Extra: cli-ux
Requires-Dist: google-cloud-secret-manager<3,>=2.16; extra == 'cli-ux'
Requires-Dist: qrcode[pil]<8,>=7.4.2; extra == 'cli-ux'
Provides-Extra: cloud
Requires-Dist: google-cloud-secret-manager<3,>=2.16; extra == 'cloud'
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.7; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pexpect<5,>=4.9; extra == 'dev'
Requires-Dist: pip-audit<3,>=2.7; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx<0.23,>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: syrupy<5,>=4.8; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers<4,>=3; extra == 'embeddings'
Provides-Extra: postgres
Requires-Dist: pgvector<1,>=0.3; extra == 'postgres'
Requires-Dist: psycopg[binary]<4,>=3.2; extra == 'postgres'
Provides-Extra: tui
Requires-Dist: pytailwindcss<1,>=0.0.4; extra == 'tui'
Requires-Dist: textual<1,>=0.70; extra == 'tui'
Provides-Extra: vector
Requires-Dist: lancedb<1,>=0.30; extra == 'vector'
Requires-Dist: pyarrow<17.0.0,>=15.0.0; (python_version < '3.14') and extra == 'vector'
Requires-Dist: pyarrow<21.0.0,>=16.0.0; (python_version >= '3.14') and extra == 'vector'
Description-Content-Type: text/markdown

# Matriosha

**Encrypted, auditable, model-agnostic, local-first AI memory for agents.**

Hold AI accountable. Own your data.

[![PyPI](https://img.shields.io/pypi/v/matriosha?style=flat-square&color=7c3aed)](https://pypi.org/project/matriosha/)
![Python](https://img.shields.io/pypi/pyversions/matriosha?style=flat-square)
![License](https://img.shields.io/badge/license-BSD--3--Clause-16a34a?style=flat-square)

## Install

Matriosha supports Python `3.11`, `3.12`, `3.13`, and `3.14`.

```bash
python3 -m pip install matriosha
```

If your environment already points `pip` to Python 3.11+, this also works:

```bash
pip install matriosha
```

## Quickstart

Initialize an encrypted local vault:

```bash
matriosha --mode local vault init
```

Remember text:

```bash
matriosha --mode local memory remember "Important launch context" --tag launch
```

Remember a file:

```bash
matriosha --mode local memory remember --file ~/Documents/agent-notes/launch-context.md --tag launch
```

Search semantically:

```bash
matriosha --mode local memory search "What is the launch motto?"
```

Verify the audit trail and vault integrity:

```bash
matriosha audit verify
matriosha vault verify
matriosha vault verify --deep
```

## Connect an agent locally

Generate a local-only token:

```bash
matriosha token generate my-agent --local --scope write --expires 30d
```

Connect a local desktop agent:

```bash
matriosha agent connect --local --name my-agent --kind desktop --token <token>
```

List local agents:

```bash
matriosha agent list --local
```

Treat generated tokens like passwords. Tokens are shown once.

## Optional custom vault location

Set `MATRIOSHA_HOME` before initializing a vault if you want a predictable local memory directory:

```bash
export MATRIOSHA_HOME=./memory
matriosha --mode local vault init
```

## Local and managed modes

Local mode is offline-first and does not require authentication.

Managed mode is optional and is designed for cloud-backed operational workflows such as login, workspace, sync, policy, quota, token workflows, and agent workflows.

```bash
matriosha auth login
matriosha --mode managed status
```

For local-only token and agent setup, use `--local` on token and agent commands.

## Why Matriosha?

AI agents are gaining longer memories, but many memory systems are opaque, vendor-bound, or difficult to verify.

Matriosha keeps AI context outside the model provider and makes it:

- **Encrypted**: vault data is protected with modern cryptography.
- **Auditable**: local audit events and vault integrity can be verified.
- **Model-agnostic**: memory is not tied to one AI vendor.
- **Local-first**: start offline, then opt into managed workflows when needed.
- **Agent-ready**: local, managed, desktop, server, and CI agent workflows are supported.

## Security model

- Argon2id passphrase hardening
- AES-256-GCM authenticated encryption
- SHA-256 and Merkle-root integrity checks
- Local audit verification
- Ed25519 signature-ready workflows
- Local-only tokens for local agent access

## Requirements

- Python `>=3.11,<3.15`
- A Unix-like shell for the examples, such as Terminal on macOS, Linux shells, or WSL/Git Bash on Windows

## Agent setup guide

For interactive VM or local-machine setup, use the public JSON guide:

- https://matriosha.in/assets/matriosha_agent_setup_guide.json

This guide is designed so AI agents can help users install, initialize, verify, and connect Matriosha safely.

## Project links

- Homepage: https://matriosha.in
- GitHub: https://github.com/drizzoai-afk/matriosha
- Issues: https://github.com/drizzoai-afk/matriosha/issues
- PyPI: https://pypi.org/project/matriosha/
- License: BSD 3-Clause
