Metadata-Version: 2.4
Name: stato
Version: 0.11.0
Summary: Capture, validate, and transfer AI agent expertise.
Project-URL: Homepage, https://stato.hiniki.com
Project-URL: Repository, https://github.com/genecell/stato
Project-URL: Documentation, https://stato.hiniki.com/getting-started/installation/
Project-URL: Bug Tracker, https://github.com/genecell/stato/issues
Author-email: Min Dai <dai@broadinstitute.org>
License: MIT
License-File: LICENSE
Keywords: agent,ai,claude,cli,codex,cursor,expertise,knowledge-transfer,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: test-agent
Requires-Dist: anyio>=4.0; extra == 'test-agent'
Requires-Dist: claude-agent-sdk>=0.1.0; extra == 'test-agent'
Requires-Dist: pytest>=8.0; extra == 'test-agent'
Description-Content-Type: text/markdown

# Stato

**The Expertise Layer for AI Agents**

Capture, validate, and transfer AI agent expertise.

[![PyPI](https://img.shields.io/pypi/v/stato)](https://pypi.org/project/stato/)
[![Tests](https://img.shields.io/badge/tests-353%20passing-green)]()
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()
[![License](https://img.shields.io/badge/license-MIT-green)]()

## What Is Stato?

**Think: npm for agent expertise, with a built-in compiler.**

Stato combines what pip does (install, share, registry) with what a compiler does (validate, reject invalid input) for a new kind of artifact: agent knowledge instead of code.

| If you know... | Stato is like... |
|---|---|
| npm / pip | Install, share, and version expertise packages |
| TypeScript / GCC | 7-pass compiler validates before anything hits disk |
| Docker | Package expertise so it works on any platform |
| Git | Snapshot, diff, and merge expertise |

What no existing tool does: the agent extracts its own knowledge (crystallization), privacy scanning before export, and a composition algebra for expertise modules.

> **Compaction is your agent's working memory. Stato is its long-term memory —
> validated, on disk, portable.** Where Mem0/Zep/Letta are services and skills
> marketplaces distribute single skills, stato distributes *whole validated
> cognitive-state archives* (context + plan + memory + skills) that any tool
> and any teammate can load.

### Three ways stato integrates with your agent

A tool needs only one tier to work with stato; each higher tier deepens it.

| Tier | What it does | How |
|---|---|---|
| **Instructions** | Static index any tool reads | `stato bridge` → AGENTS.md, CLAUDE.md, `.cursor/rules/*.mdc`, copilot, GEMINI.md, SKILL.md |
| **Hooks** | Auto-restore state after compaction | `stato hooks install` → Claude Code, Codex CLI, Gemini CLI |
| **MCP** | Live state + validate-gated writes | `stato mcp` → every MCP client at once |

### Quickstart per agent

One command wires stato into your agent (it then reads the generated guidance
automatically):

| Agent | One command |
|---|---|
| **Claude Code** | `pip install stato && stato bridge --platform claude` |
| **Codex CLI** | `pip install stato && stato bridge --platform agents` |
| **Cursor** | `pip install stato && stato bridge --platform cursor` |
| **Gemini CLI** | `pip install stato && stato bridge --platform gemini` |
| **GitHub Copilot** | `pip install stato && stato bridge --platform copilot` |
| **Any MCP client** | `pip install "stato[mcp]" && stato init --mcp` then run `stato mcp` |

Deeper integration (optional): `stato skill install --tool <agent>` ships the
"how to use stato" skill, and `stato init --mcp` exposes live tools like
`stato_workspace(task)`.

**Starting from scratch** (no `.stato/` yet): `pip install stato && stato init
&& stato crystallize`, then tell your agent to *"read and follow
`.stato/prompts/crystallize.md`"*, then `stato validate .stato/` and
`stato bridge --platform <agent>`.

![Stato Overview](docs/figures/stato_figures.png)

## Install

    pip install stato

Install from GitHub (latest development version):

    pip install git+https://github.com/genecell/stato.git

## Quick Start

### Across Sessions (Same Project)

Your agent forgets between sessions. Stato makes its knowledge persist on disk.

    # Session 1: agent captures expertise
    cd my-project
    stato init
    stato crystallize
    # Saves prompt to .stato/prompts/crystallize.md

    # Ask your coding agent to capture its expertise:
    #   "Read and follow .stato/prompts/crystallize.md"
    # Agent writes .stato/ modules based on what it learned.

    # Verify and generate bridge
    stato validate .stato/
    stato bridge --platform claude

    # Session 2 (next day, after /compact, new terminal):
    # CLAUDE.md and .stato/ files are still on disk.
    # Agent reads CLAUDE.md automatically.
    stato resume             # structured recap if needed

No export. No import. Files on disk persist across every session.

### Across Projects and People

Transfer expertise to a new project, a teammate, or the community.

    # Export
    stato snapshot --name scrna-expert --sanitize

    # Import into new project
    cd ~/new-project && stato init
    stato import scrna-expert.stato

    # Or install from the community registry
    stato registry install genecell/scrna-expert

**Composition algebra** for working with expertise archives:

| Operation | Command | What it does |
|---|---|---|
| Snapshot | `stato snapshot` | Bundle all expertise into a portable archive |
| Slice | `stato slice --module skills/qc` | Extract specific skills with dependencies |
| Graft | `stato graft external-skill.py` | Add one external skill with validation |
| Merge | `stato merge a.stato b.stato` | Combine expertise from multiple sources |

### Across Platforms

Same expertise, different coding agents. One command generates every bridge:

    stato bridge --platform all

    # Creates the file each tool reads automatically:
    #   AGENTS.md                           -> Codex, and most agents (cross-tool standard)
    #   CLAUDE.md                           -> Claude Code
    #   .cursor/rules/stato.mdc             -> Cursor
    #   .github/copilot-instructions.md     -> GitHub Copilot
    #   GEMINI.md                           -> Gemini CLI
    #   README.stato.md                     -> anything else / humans

### From Web AI to Coding Agent

Plan architecture in Claude.ai or ChatGPT. Build in any coding agent.

    stato crystallize --web
    # Paste prompt into web AI -> get bundle -> save as stato_bundle.py
    stato import-bundle stato_bundle.py
    stato bridge --platform cursor

## Why Stato Exists

AI coding agents are powerful but stateless. Every session starts from zero. Expertise earned in one session, one project, or one platform stays trapped there.

Stato treats agent expertise like code: captured in structured modules, validated by a 7-pass compiler, composed with algebraic operations, and portable across any platform. Your agent's knowledge becomes a permanent, shareable, validated artifact.

[Read the full story ->](https://stato.hiniki.com)

## Features

| Feature | Description |
|---|---|
| Crystallize | Agent captures its own knowledge into structured modules |
| 7-Pass Compiler | Validates syntax, structure, types, schema, semantics before writing |
| Composition Algebra | Snapshot, slice, graft, merge expertise archives |
| Cross-Platform Bridges | AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, Copilot, GEMINI.md, SKILL.md from one source |
| Web AI Bridge | Import expertise from Claude.ai, ChatGPT, Gemini conversations |
| Privacy Scanner | 19 patterns detect secrets, emails, paths before export |
| Resume | Restore full context after /compact or session restart |
| Convert | Migrate existing CLAUDE.md, .cursorrules, SKILL.md into stato |
| Registry | Search and install community expertise packages |
| Diff | Field-level comparison between module versions |

## CLI Reference

| Command | Description |
|---|---|
| `stato init` | Initialize a stato project |
| `stato crystallize` | Save prompt for agent to capture expertise |
| `stato crystallize --print` | Print full crystallize prompt to terminal |
| `stato crystallize --web` | Generate prompt optimized for web AI |
| `stato validate` | Run 7-pass compiler on modules |
| `stato status` | Show all modules, plan progress, warnings |
| `stato bridge` | Generate platform bridge files |
| `stato resume` | Generate context recap for session restoration |
| `stato diff` | Compare module versions |
| `stato snapshot` | Export expertise as portable archive |
| `stato import` | Import modules from .stato archive |
| `stato import-bundle` | Import from web AI bundle file |
| `stato inspect` | Preview archive contents |
| `stato slice` | Extract specific modules with dependencies |
| `stato graft` | Add external module with validation |
| `stato merge` | Combine two archives with conflict resolution |
| `stato convert` | Migrate from CLAUDE.md, .cursorrules, SKILL.md |
| `stato registry list` | List available packages |
| `stato registry search` | Search packages by keyword |
| `stato registry install` | Install a community package |

Full documentation: [stato.hiniki.com](https://stato.hiniki.com/getting-started/installation/) | [USAGE.md](USAGE.md)

## Comparison

| Capability | Stato | Plain CLAUDE.md | SkillKit | MemGPT | CrewAI |
|---|---|---|---|---|---|
| Validated modules | 7-pass compiler | No validation | No validation | No | No |
| Cross-platform | 4 platforms | Claude only | Claude only | OpenAI only | Framework-locked |
| Composition algebra | snapshot, slice, graft, merge | Manual copy | No | No | No |
| Privacy scanning | 19 patterns | None | None | None | None |
| Web AI bridge | Import from any chat | No | No | No | No |
| Agent self-capture | Crystallize prompt | Human-authored | Human-authored | Auto (opaque) | Config files |
| Package registry | GitHub-based | No | No | No | No |
| Session resume | Structured recap | Re-read file | No | Built-in | No |

## Registry

Browse and install shared expertise packages:

    stato registry list
    stato registry search "bioinformatics"
    stato registry install scrna-expert

## Contributing

https://github.com/genecell/stato

Issues and PRs welcome.

## Contact

Min Dai - dai@broadinstitute.org

[Fishell Laboratory](https://fishelllab.hms.harvard.edu/), Harvard Medical School and the Broad Institute of MIT and Harvard.

## License

MIT
