Metadata-Version: 2.5
Name: magicite
Version: 1.0.0
Summary: Local-first plasticity-inspired skill router speaking MCP over stdio.
Project-URL: Homepage, https://github.com/Rynaro/magicite
Project-URL: Repository, https://github.com/Rynaro/magicite
Project-URL: Issues, https://github.com/Rynaro/magicite/issues
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=48.0.1
Requires-Dist: fastembed>=0.4
Requires-Dist: jsonschema>=4.21
Requires-Dist: mcp<3.0,>=2.0
Requires-Dist: numpy>=1.26
Requires-Dist: packaging>=23
Requires-Dist: pydantic>=2.6
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: structlog>=24.1
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: leiden
Requires-Dist: leidenalg>=0.10; extra == 'leiden'
Requires-Dist: python-igraph>=0.11; extra == 'leiden'
Description-Content-Type: text/markdown

<div align="center">

<img src="docs/assets/magicite-logo.png" alt="Magicite" width="800">

### Local skills with explicit routing and review.

Magicite is a local-first MCP server that routes an agent to the right skill,
captures what happened, and turns that evidence into reviewable improvements.

[![CI](https://github.com/Rynaro/magicite/actions/workflows/ci.yml/badge.svg)](https://github.com/Rynaro/magicite/actions/workflows/ci.yml)
[![Version](https://img.shields.io/badge/version-1.0.0-7c3aed)](docs/releases/1.0.0.md)
[![Python](https://img.shields.io/badge/python-3.12-3776ab?logo=python&logoColor=white)](pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-stdio-0f766e)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/github/license/Rynaro/magicite)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/Rynaro/magicite?style=flat)](https://github.com/Rynaro/magicite/stargazers)

[Quick start](#quick-start) · [How it works](#how-it-works) ·
[Engrams](#the-engram-format) · [Evidence](#evidence-without-hand-waving) ·
[Documentation](#documentation)

</div>

---

Most agent skill registries are static catalogs: they can describe what a
skill does, but they do not learn which skills work together, where they fail,
or when they should stay out of the way.

Magicite adds that missing lifecycle. Skills live as portable `.egr.md`
**engrams**. The stable `dense-v1` policy ranks eligible skills from their full canonical
routing content. Adaptive routing is explicitly experimental and cannot replace
the stable incumbent without reviewed evidence. A resumable
**Dream** cycle consolidates useful evidence back into reviewable files.

The boundary is intentional: **Magicite stores, routes, and audits skills. It
never executes them.** Your agent host remains responsible for permissions,
sandboxing, and execution.

## Why Magicite?

| | What Magicite provides |
|---|---|
| **Local by default** | stdio MCP, project-local SQLite/WAL, offline embeddings after one explicit model fetch, and no hosted control plane. |
| **Portable by design** | Human-readable `.egr.md` files are the source of truth. The database is a disposable index that can be rebuilt from them. |
| **Stable by default** | `dense-v1` is nonadaptive; Dream and learned weights cannot change stable ordering. Adaptive policy selection is experimental. |
| **Graph-aware** | Skills can declare dependencies, composition, and inhibition; routing can return an ordered multi-skill plan rather than only one winner. |
| **Governed** | Every tool has a risk and side-effect class. Durable lifecycle changes are approval-gated by default and leave an audit trail. |
| **Host-agnostic** | Any MCP client can use the core server. Hooks improve signal quality, but they are an adapter—not a dependency. |

Version **1.0.0** ships the existing local MCP knowledge workflow under the
[approved functional release scope](docs/releases/1.0.0.md). Distribution uses
GitHub wheel/source packages and signed OCI; production PyPI is deferred.
Linux protected custody and Python 3.11/3.12 are the supported runtime profile.
Scale performance, retrieval quality, production adoption, and production macOS
custody remain unqualified. See [current authority](docs/AUTHORITY.md) and the
[operator tutorial](docs/operator-tutorial.md).

## Quick start

Add Magicite alongside your project as a stdio MCP server. Follow these three
references in order:

| Reference | What you do |
|---|---|
| [Install](docs/install.md) | Verify the published wheel and install it in a permanent Python 3.11/3.12 environment. |
| [Setup](docs/setup.md) | Have a Linux administrator provision independent protected custody for the project. |
| [Quick Setup](docs/quick-setup.md) | Fetch the model, connect MCP, import and approve a skill, then route and load its body. |

Once Install and Setup are complete, **[Quick Setup](docs/quick-setup.md)** is the
short project-user path. Custody is mandatory and must be provisioned by an
administrator before project connection. macOS production custody remains unqualified. Keep
autonomous approval disabled and review each imported skill's exact digest.

### One-command project connection

Version 1.0.0 includes `magicite init`. After [Install](docs/install.md) and
administrator [Setup](docs/setup.md):

```bash
magicite init --host claude --project-root /absolute/path/to/project
```

Inside the enrolled project, omit `--project-root`. Init checks protected custody
and performs an offline model inference before merging `.mcp.json` and one owned
`CLAUDE.md` instruction block. It preserves other servers and instructions, keeps
private backups of changed existing files, and verifies a local MCP handshake.
Reconnect Claude Code afterward. This does not provision the machine or qualify
Claude model execution.

If the model is missing, the interactive command offers a separate default-no
network download. `--fetch-model` supplies only model-download consent; it never
imports or approves skills. A terminal operator may separately elect import from
`skills/` (or `--skills path`) and approve each displayed digest with an explicit
identity. Noninteractive runs configure and verify, then print manual import and
review commands. Approval does not promote imported drafts; an empty registry is
connected with skill preparation still remaining. See [Quick Setup](docs/quick-setup.md)
for failure recovery and the manual connection path.

The repository's 30 first-party engrams are examples requiring the same review;
their count is not evidence of a break-even point or routing quality.

### Container deployment

The release workflow targets `linux/amd64` and `linux/arm64`. Its images run as a
non-root user and bake the FastEmbed model during the build, with offline MCP handshake checks in CI. Published v1 channel validation remains
UNEVALUATED. Pin the image by the digest published on the
matching [GitHub Release](https://github.com/Rynaro/magicite/releases):

```bash
MAGICITE_IMAGE='ghcr.io/rynaro/magicite@sha256:<release-digest>'

docker run --rm -i \
  --user "$(id -u):$(id -g)" \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  -v "$PWD":"$PWD":z \
  -w "$PWD" \
  "$MAGICITE_IMAGE" \
  serve --project-root "$PWD"
```

The `--user` mapping is required for bind-mounted projects: Magicite creates
and updates project-local state, so the container must write with the host
owner's UID and GID. See the [operations runbook](docs/operations.md) for the
complete deployment and filesystem guidance.

## How it works

```mermaid
flowchart TD
    Q["Agent query"] --> R["Route: rank and compose"]
    R --> H["Host loads and executes a skill"]
    H --> S["Use and outcome signals"]
    S --> D["Dream: replay, prune, distill, audit, checkpoint"]
    D --> E["Reviewable .egr.md registry"]
    E --> R
```

Magicite separates the system into three paths:

- **Hot path:** check trust and typed eligibility, embed full canonical routing
  content under `dense-v1`, apply the selected abstention thresholds (accuracy remains unqualified), and
  return a validated bounded plan when selection is allowed.
- **Signal path:** record session-scoped use and outcome evidence without
  writing learned state into skill files.
- **Dream path:** consolidate durable node and edge state through resumable,
  lease-fenced phases, then checkpoint deterministic changes to disk.

The storage model keeps authority legible:

```text
.magicite/
├── engrams/              # portable source of truth
│   ├── *.egr.md
│   └── skill-graph.db    # local, rebuildable index; ignored by default
├── archive/              # lifecycle archive; never silent deletion
├── approvals/            # durable approval mirrors
└── runtime/              # local coordination and adapter state
```

Multiple readers and session writers share SQLite WAL. All durable writers use
one cross-process lease with fencing tokens, so a stale process cannot publish
after losing ownership. Dream and idempotent MCP writes can recover after
process death without replaying already-committed work.

Read the full [architecture](docs/02-architecture.md) and
[learning model](docs/03-learning-model.md).

## The engram format

An engram combines routing intent, contraindications, composition contracts,
plasticity, trust, and an append-only provenance journal in one Git-friendly
Markdown artifact.

```yaml
---
spec: engram/0.2
name: magicite-honest-claim-scope
id: egr_3579bb59
version: 1
provenance: authored

intent:
  does: "State what Magicite's evidence does and does not license"
  use_when: "reviewing a claim about routing, graph, or learning capability"
  not_when: "producing the measurement itself"

triggers:
  positive:
    - "review a magicite claim for overstatement"
  negative:
    - "run the retrieval benchmark"

needs: [magicite-run-retrieval-benchmark]
yields: [calibrated-claim]
composes: []
inhibits: []

trust:
  origin: authored
  verification_status: pending
---

## Procedure
1. Start from the falsification record, not the feature list.
2. State what the measurement supports and what it does not.
```

This is a legacy `engram/0.2` example, retained for the dual reader. New typed
artifacts use `engram/1.0`; see the [current schema](src/magicite/engram/schema/engram-1.0.schema.json).
For the legacy format:

- `intent` and positive triggers form the versioned positive routing view;
- `not_when` and negative triggers form a separate contraindication view;
- `needs` and `composes` participate in bounded plan expansion;
- `yields` is portable metadata in 0.3, not yet a graph edge;
- lifecycle, verification, and operation-execution status remain independent;
- learned state and every mutation remain inspectable and attributable.

See the [engram specification](docs/04-engram-format.md) and the bundled
[JSON Schema](src/magicite/engram/schema/engram-0.2.schema.json).

## The 16-tool surface

The public MCP API is intentionally small and generated from the same registry
used by the server and tests.

| Area | Tools | Side effects |
|---|---|---|
| Retrieve and inspect | `route`, `load_skill_body`, `introspect`, `flag_dead` | R0 / none |
| Capture signals | `signal_use`, `signal_outcome`, `session_end` | R1 / ephemeral |
| Manage the registry | `register`, `sync`, `checkpoint`, `export` | R2 / project-local |
| Govern lifecycle | `nucleate`, `sharpen`, `promote`, `archive` | R3 / approval-gated |
| Consolidate | `consolidate` | R3 / resumable batch |

Inspect the authoritative schemas directly:

```bash
uv run magicite tools
```

Unknown fields are rejected. Writes support request-level idempotency, and the
server exposes no R4/R5 network, shell, raw SQL, or arbitrary filesystem tool.

## Trust and integrity

Magicite treats adaptive behavior as a governance problem, not just a ranking
problem.

- **No skill execution:** code blocks remain inert text; the host owns execution
  and its permission boundary.
- **Offline source use:** FastEmbed is the production provider, but runtime
  lookup is offline by default after explicit acquisition.
- **Untrusted input handling:** imported engrams are scanned and can be held in
  pending or quarantined verification states.
- **Approval-gated change:** R3 operations propose durable lifecycle mutations
  for review unless autonomous mode is explicitly enabled.
- **Recoverable writes:** atomic publication, fencing tokens, phase cursors, and
  deterministic checkpoints protect file and database integrity.
- **Secret hygiene:** adapter tokens are recursively redacted before canonical
  event and idempotency hashing.
- **Supply chain:** release workflows use immutable action references, scan the
  image, and produce signatures, SBOMs, and provenance attestations.

For the exact model, read [trust, governance, and lifecycle](docs/06-trust-governance-lifecycle.md)
and the [operations runbook](docs/operations.md).

## Evidence, without hand-waving

Magicite separates **implemented capability** from **validated hypothesis**.
That distinction is part of the product.

| Claim | Current evidence |
|---|---|
| Portable registry, rebuildable index, governed lifecycle, and recoverable Dream execution | Mechanically verified by unit, integration, acceptance, and spawned-process crash tests. |
| Offline stdio server and hardened container handshake | Verified in CI with networking disabled for the runtime path. |
| Hybrid or adaptive routing beats the stable dense incumbent | **UNEVALUATED for v1.** Historical negative results remain in the linked falsification record; they do not qualify new claims. |
| Graph activation and learned state improve routing | **Not demonstrated.** The central declared-edge hypothesis still needs an independent, purpose-built evaluation. |
| A roughly 50-skill break-even point exists | **Not demonstrated.** It remains a historical reference size, not a product claim. |
| Production latency at the proposed supported scale | **UNEVALUATED.** Dedicated production-model measurements and both synthetic and licensed real corpus evidence are required. |

The historical study is bounded: one author, one annotator, one embedder, and a
uniform learning workload. Mechanism repairs between releases are not presented
as validation of the underlying hypothesis.

Read the [falsification record](docs/01-vision-and-hypotheses.md) and
[evaluation methodology](docs/07-evaluation-and-observability.md), or validate
the versioned composition corpus and superseding result artifact:

```bash
uv run python -m magicite.eval validate-corpus docs/evaluation/composition-v0.3.json
uv run python scripts/check_evaluation_results.py docs/evaluation/v0.3-results.json
```

For a registry with independently labelled queries, `magicite-bench` runs the
four comparable lexical, embedding, structural, and production baselines; see
the [benchmark harness guide](docs/operations.md#11-the-magicite-bench-harness-standing-kpis-and-ablations-m6).

## Dogfooding

Magicite routes maintenance of its own repository through 30 first-party
engrams connected by declared dependency and inhibition edges. A real stdio MCP
driver exercises all 16 tools; graph guards check dangling targets and stale
code references.

```bash
uv run python scripts/dogfood_graph_check.py --edges
uv run python scripts/dogfood_graph_check.py --symbols
uv run python scripts/dogfood_session.py --out /tmp/magicite-session.json
```

This proves end-to-end wiring, not retrieval quality. The
[dogfooding report](docs/adapters/dogfooding.md) records both what worked and
what the exercise exposed.

## Configuration

Configuration resolves from defaults, then `.magicite/magicite.toml`, then
`MAGICITE_*` environment variables.

| Variable | Purpose |
|---|---|
| `MAGICITE_EMBEDDING_PROVIDER` | `fastembed` (default), `hashing` for deterministic tests, or optional `ollama`. |
| `MAGICITE_EMBEDDING_OFFLINE` | Refuse runtime model downloads when set to `1`. |
| `MAGICITE_HOOK_TOKEN` | Enable trusted Tier-2 host-adapter signals. Never place it in an engram. |
| `MAGICITE_AUTONOMOUS` | Opt into autonomous R3 execution for a trusted registry. Review mode is the default. |

All routing, plasticity, consolidation, retention, and plan bounds are
documented in the [operations configuration reference](docs/operations.md#10-quick-reference--environment-variables).

## Documentation

| Read this | For |
|---|---|
| [Install](docs/install.md) | Published wheel, checksum verification, and permanent Python environment. |
| [Setup](docs/setup.md) | Linux administrator custody prerequisites and manual provisioning. |
| [Quick Setup](docs/quick-setup.md) | First approved project skill through MCP. |
| [Authority manifest](docs/AUTHORITY.md) | What defines the functional v1 promise when historical records disagree. |
| [Documentation index](docs/README.md) | The complete reading order and terminology. |
| [Vision and hypotheses](docs/01-vision-and-hypotheses.md) | Problem statement, falsification record, and research agenda. |
| [Architecture](docs/02-architecture.md) | Hot/write/Dream paths, storage, concurrency, and security boundary. |
| [Learning model](docs/03-learning-model.md) | Plasticity, signals, decay, and consolidation semantics. |
| [Engram format](docs/04-engram-format.md) | Portable artifact schema and lifecycle. |
| [Protocol and signals](docs/05-protocol-and-signals.md) | Tool contracts and Tier-0/1/2 signal ladder. |
| [Trust and governance](docs/06-trust-governance-lifecycle.md) | Risk classes, approvals, provenance, and recovery. |
| [Evaluation](docs/07-evaluation-and-observability.md) | Baselines, metrics, experiments, and observability. |
| [Operations](docs/operations.md) | Deployment, diagnostics, concurrency, recovery, and release channels. |

## Development

```bash
uv sync --all-extras

uv run ruff check .
uv run mypy src
uv run pytest -q -m "not benchmark"
uv run pytest -q -m acceptance
uv run magicite tools | jq '.tools | length'  # 16
```

The hardened-image gate additionally builds the production container, performs
the offline MCP smoke test, runs the production benchmark matrix, and fails on
HIGH/CRITICAL vulnerabilities.

To work on Magicite effectively, start with [AGENTS.md](AGENTS.md) and
[EIDOLONS.md](EIDOLONS.md). The repository uses its own engrams to route
maintenance decisions, and the CI contract expects documentation claims to
remain synchronized with the runtime.

## Project status

Magicite 1.0.0 is the bounded functional release described in the
[release notes](docs/releases/1.0.0.md).
The portable format, MCP surface, integrity model, lifecycle governance, and
Dream recovery are implemented. The research question—whether graph and
plasticity layers improve routing over simpler retrieval—remains open by
design, measured rather than assumed.

See [CHANGELOG.md](CHANGELOG.md) for release history and
[GitHub Releases](https://github.com/Rynaro/magicite/releases) for historical
artifacts. The v1 channels are GitHub wheel/source packages and signed OCI.

## License

Magicite is available under the [Apache License 2.0](LICENSE).
