<p align="center">
  <img src=".github/assets/strata-banner.svg" alt="Strata. One memory. Every agent." width="100%">
</p>

<p align="center">
  <a href="https://github.com/rx6ru/strata/actions/workflows/ci.yml"><img src="https://github.com/rx6ru/strata/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="https://github.com/rx6ru/strata/releases/latest"><img src="https://img.shields.io/github/v/release/rx6ru/strata" alt="Latest release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0b0f19" alt="MIT license"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="docs/agent-skill.md">Agent skill</a> ·
  <a href="docs/operations.md">Operations</a> ·
  <a href="docs/security-model.md">Security</a>
</p>

# Strata

Portable agent memory. Append-only records, verified provenance, MCP tools, and self-hosting.

Strata gives a team one durable memory that any agent can read and update without mixing projects, leaking secrets, or rewriting history. It is built for work that moves across people, sessions, machines, and runtimes.

## Why it exists

Local agent memory breaks when work moves across machines, people, tools, or old sessions. Strata keeps the facts that should outlive one agent run:

- experiment results and decisions;
- dataset notes, source checksums, and extraction status;
- procedures that worked and mistakes to avoid;
- project handoffs for agents joining later.

Strata does not store secrets, raw transcripts, chain-of-thought, API keys, or provider settings.

## What ships

| Part | What it does |
| --- | --- |
| `strata` Python package | CLI, append-only store, REST gateway, MCP bridge, policy checks, export, and restore. |
| `skills/strata` | Shareable agent skill for reading, writing, and safe service control without hardcoded host values. |
| `policy` and `schema` | Rules and JSON contracts agents must follow before writes. |
| `scripts` and `deploy` | Local, Docker, and systemd helpers for running the service. |

## Quick start

```bash
git clone https://github.com/rx6ru/strata.git
cd strata
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .
strata --help
```

Start a local gateway:

```bash
strata serve --root /tmp/strata-demo --host 127.0.0.1 --port 8787
```

Check it from another shell:

```bash
curl -fsS http://127.0.0.1:8787/healthz
curl -fsS -H 'X-Strata-Client: 1' http://127.0.0.1:8787/v1/status
```

If you are running from a source checkout before installing the package:

```bash
PYTHONPATH=. python -m strata --help
PYTHONPATH=. python -m strata root-hash --root /tmp/strata-demo
```

Read the full setup guide in [docs/getting-started.md](docs/getting-started.md).

## How agents use it

1. Copy `skills/strata/` into the agent runtime skill directory.
2. Give the agent only non-secret runtime values, such as the gateway URL, namespace, current task, SSH alias, and optional lifecycle wrapper path.
3. The agent fetches policy, prepares scoped context, reads canonical records, and writes only verified durable knowledge.
4. Corrections append superseding records. Reorganization appends relocation, split, merge, or invalidation events. Ordinary agents never edit history in place.

The skill does not hardcode hostnames, IP addresses, EC2 instance IDs, usernames, API keys, project namespaces, policy hashes, roots, or record IDs. See [docs/agent-skill.md](docs/agent-skill.md).

## How writes stay clean

Strata checks every write before commit:

- current policy hash is acknowledged before commit;
- schemas validate the record;
- idempotency keys prevent duplicate retries;
- append-only SQLite triggers block in-place history edits;
- content hashes and root manifests make exports checkable;
- secret and raw transcript scanners reject unsafe payloads;
- derived recall is labeled as navigation, not truth.

## Self-hosting

For the Docker stack:

```bash
./scripts/configure.sh
./scripts/control.sh start
```

For a system service, use the installation guide and the constrained lifecycle wrapper in `deploy/`. Remote agents should call only that wrapper for `status`, `start`, `stop`, or `restart`.

The default deployment has no app-level users. Keep it on loopback, a private network, SSH, VPN, firewall, or your own proxy/auth layer. Read [docs/security-model.md](docs/security-model.md) and [SECURITY.md](SECURITY.md) before team hosting.

## REST and MCP

The REST gateway exposes health, policy, status, search, recall, record, append, supersede, relocate, split, merge, and invalidate endpoints under `/v1`.

The MCP bridge exposes matching tools such as `memory_policy`, `memory_prepare_context`, `memory_search`, `memory_get`, `memory_capture_verified`, and `memory_status`.

## Evaluation

```bash
PYTHONPATH=. python -m strata eval --input tests/fixtures/strata_eval/cases.json
```

The fixture checks namespace isolation, provenance, promotion and rejection behavior, derived recall labels, and forbidden-value leakage.

## License

MIT. See [LICENSE](LICENSE). Third-party notes are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).