Metadata-Version: 2.4
Name: matriosha
Version: 0.1.0
Summary: Matriosha Core CLI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography<43,>=42
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: click<8.2,>=8.1
Requires-Dist: rich<14,>=13.7
Requires-Dist: numpy<2,>=1.26
Requires-Dist: httpx<0.28,>=0.27
Requires-Dist: typer<0.13,>=0.12
Requires-Dist: argon2-cffi<24,>=23.1
Requires-Dist: keyring<26,>=25
Requires-Dist: pynacl<2,>=1.5
Requires-Dist: platformdirs<5,>=4.2
Requires-Dist: portalocker<3,>=2.8
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: python-dotenv<2,>=1.0
Requires-Dist: fastapi<1,>=0.110
Requires-Dist: uvicorn[standard]<1,>=0.28
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: respx<0.23,>=0.22; extra == "dev"
Dynamic: license-file

```text
╔══════════════════════════════════════════════════════════════════════════════════════════════╗
║ 10110010  01001101  00110101  11010010  01101001  10010111  00110011  01011010  11100010     ║
║                                                                                              ║
║     ███╗   ███╗  █████╗  ████████╗ ██████╗  ██╗  ██████╗  ███████╗ ██╗  ██╗  █████╗          ║
║     ████╗ ████║ ██╔══██╗ ╚══██╔══╝ ██╔══██╗ ██║ ██╔═══██╗ ██╔════╝ ██║  ██║ ██╔══██╗         ║
║     ██╔████╔██║ ███████║    ██║    ██████╔╝ ██║ ██║   ██║ ███████╗ ███████║ ███████║         ║
║     ██║╚██╔╝██║ ██╔══██║    ██║    ██╔══██╗ ██║ ██║   ██║ ╚════██║ ██╔══██║ ██╔══██║         ║
║     ██║ ╚═╝ ██║ ██║  ██║    ██║    ██║  ██║ ██║ ╚██████╔╝ ███████║ ██║  ██║ ██║  ██║         ║
║     ╚═╝     ╚═╝ ╚═╝  ╚═╝    ╚═╝    ╚═╝  ╚═╝ ╚═╝  ╚═════╝  ╚══════╝ ╚═╝  ╚═╝ ╚═╝  ╚═╝         ║
║                                                                                              ║
║ 01011101  11001010  00101101  10100110  01110001  00011101  10011001  01101100  10101010     ║
╚══════════════════════════════════════════════════════════════════════════════════════════════╝
```

# matriosha

> “Visibility is a trap.”  
> — Michel Foucault, *Discipline and Punish: The Birth of the Prison* (1975)

[![PyPI version](https://img.shields.io/pypi/v/matriosha.svg)](https://pypi.org/project/matriosha/)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-green.svg)](./LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/drizzoai-afk/matriosha/ci.yml?branch=main&label=ci)](https://github.com/drizzoai-afk/matriosha/actions/workflows/ci.yml)

Token-efficient memory infrastructure for humans and agents, with local-first encryption, user-owned data, and verifiable audit trails.

---

## Table of Contents

- [Why Matriosha](#why-matriosha)
- [Value Proposition](#value-proposition)
- [Key Features](#key-features)
- [Quick Start](#quick-start)
- [One-Shot Agent Connection Flow](#one-shot-agent-connection-flow)
- [Usage Examples](#usage-examples)
- [Local vs Managed Mode](#local-vs-managed-mode)
- [Architecture and Extensibility](#architecture-and-extensibility)
- [Documentation](#documentation)
- [Development and Quality Gates](#development-and-quality-gates)
- [Contributing](#contributing)
- [Community and Support](#community-and-support)
- [License](#license)

---

## Why Matriosha

Most AI memory systems optimize for convenience, not sovereignty. Matriosha flips that default:

- **Token-efficient memory layer**: compact storage and retrieval flows designed for practical agent workloads.
- **User ownership**: your local vault, your passphrase, your control surface.
- **Auditability**: deterministic command paths and explicit action trails for security review.

## Value Proposition

Matriosha helps you run memory + token workflows that are:

1. **Secure by default** (local vault + encrypted artifacts)
2. **Operationally simple** (clear CLI primitives)
3. **Future-proof** (plugin contract for managed extensions)

## Key Features

- Local-first encrypted vault initialization and verification
- Local agent token lifecycle: generate, inspect, list, revoke
- Local agent connection primitives for desktop/server/CI agents
- Pluggable architecture via `matriosha.plugins` entry points
- Command-level JSON output support for automation
- CI-backed quality gates (ruff, mypy, pytest + coverage)

---

## Quick Start

### Prerequisites

- Python **3.11+**
- `pip`

### Install from source (recommended for contributors)

```bash
git clone https://github.com/drizzoai-afk/matriosha.git
cd matriosha
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

### Verify installation

```bash
matriosha --help
matriosha vault init --help
```

### Initialize local secure workspace

```bash
matriosha vault init
matriosha vault verify
```

### Generate a local token

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

---

## One-Shot Agent Connection Flow

Use this when an agent needs a quick local bootstrap with minimal ceremony.

```bash
# 1) Initialize vault (one-time per profile)
matriosha vault init

# 2) Generate a local token for the agent
matriosha token generate my-agent --local --scope read --expires 24h

# 3) Connect agent in local mode
matriosha agent connect --local --name my-agent --kind server --token <PASTE_TOKEN>
```

For automation, prefer `--json` where available and pass secrets through secure environment handling rather than shell history.

---

## Usage Examples

### Script-friendly token generation

```bash
matriosha token generate ci-runner --local --scope admin --expires 30m --json
```

### Inspect and revoke a token

```bash
matriosha token inspect <TOKEN_ID> --json
matriosha token revoke <TOKEN_ID> --json
```

### Connect a desktop agent in plain output mode

```bash
matriosha --plain agent connect --local --name analyst-laptop --kind desktop --token <PASTE_TOKEN>
```

---

## Local vs Managed Mode

| Capability | Local mode (`--local`) | Managed mode (plugin-backed) |
|---|---|---|
| Data residency | User-controlled local environment | Service-managed environment |
| Token generation | Built into the CLI | Delegated via plugin hook (`token_generate`) |
| Agent connect | Built into the CLI | Delegated via plugin hook (`agent_connect`) |
| Billing/auth commands | Not in the CLI | Added by managed plugin |
| Offline operation | Yes | Usually no |
| Best for | Sovereign workflows, private dev, edge devices | Centralized fleet operations, hosted control planes |

If you call managed flows without a managed plugin installed, the CLI returns explicit guidance (e.g., install `matriosha-managed` or use `--local`).

---

## Architecture and Extensibility

Matriosha keeps managed concerns out of the trust boundary. Extend behavior via plugin entrypoints:

- Entry point group: `matriosha.plugins`
- Hook model for selective command interception
- Clear contracts for token and agent command extension

See docs for hook names, behavior, and integration examples.

## Documentation

- [Plugin contract and hooks](./docs/EXTENSIBILITY.md)
- [Dependency bootstrap and `matriosha init`](./docs/DEPENDENCIES.md)
- [Decoder plugin notes](./docs/DECODER_PLUGINS.md)
- [ADR index](./docs/adr/README.md)
- [Security policy](./SECURITY.md)

---

## Development and Quality Gates

```bash
pip install -e .[dev]
ruff check src tests
ruff format --check src tests
mypy --strict
pytest -q --cov --cov-report=term-missing
```

CI runs on pushes and pull requests to keep quality bars consistent.

## Contributing

Contributions are welcome.

1. Fork the repository
2. Create a feature branch
3. Add tests and docs for your change
4. Run quality gates locally
5. Open a pull request

## Community and Support

- Open issues for bugs and feature requests
- Use PR discussions for design-level changes
- Security-sensitive reports: follow [`SECURITY.md`](./SECURITY.md)

## License

Distributed under the **BSD 3-Clause License**. See [`LICENSE`](./LICENSE).
