magicite 1.0.0

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.

Quick start · How it works · Engrams · Evidence · Documentation

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?

Version 1.0.0 ships the existing local MCP knowledge workflow under the approved functional release scope. 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 and the operator tutorial.

Quick start

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

Once Install and Setup are complete, Quick Setup 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 and administrator Setup:

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 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:

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 for the complete deployment and filesystem guidance.

How it works

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:

.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 and learning model.

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.

---
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. 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 and the bundled JSON Schema.

The 16-tool surface

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

Inspect the authoritative schemas directly:

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 and the operations runbook.

Evidence, without hand-waving

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

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 and evaluation methodology, or validate the versioned composition corpus and superseding result artifact:

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.

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.

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 records both what worked and what the exercise exposed.

Configuration

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

All routing, plasticity, consolidation, retention, and plan bounds are documented in the operations configuration reference.

Documentation

Development

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 and 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. 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 for release history and GitHub 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.