matriosha 0.1.0

Matriosha Core CLI

╔══════════════════════════════════════════════════════════════════════════════════════════════╗
║ 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)

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

---

Table of Contents

• Why Matriosha
• Value Proposition
• Key Features
• Quick Start
• One-Shot Agent Connection Flow
• Usage Examples
• Local vs Managed Mode
• Architecture and Extensibility
• Documentation
• Development and Quality Gates
• Contributing
• Community and Support
• 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)

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

Verify installation

matriosha --help
matriosha vault init --help

Initialize local secure workspace

matriosha vault init
matriosha vault verify

Generate a local token

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.

# 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

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

Inspect and revoke a token

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

Connect a desktop agent in plain output mode

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
• Dependency bootstrap and matriosha init
• Decoder plugin notes
• ADR index
• Security policy

---

Development and Quality Gates

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

License

Distributed under the BSD 3-Clause License. See LICENSE.