ayxuerui/contexture

Contexture (ctxr)

Your agents' long-term knowledge — they write it, you review it before it lands.

Contexture turns a git repository into shared, durable knowledge, and ships the operating procedures an AI agent needs to work it: what to do with a new source, where a note belongs, when a synthesis has gone stale, how a change gets reviewed and landed. Every write lands the way code does — in a branch, past a health check, through a pull request you approve.

This is one layer of agent memory — the shared one. Your harness keeps what an agent knows about you and itself; contexture keeps what you know, reviewed and versioned, outliving any single agent or session. Claude Code, Codex, Cursor, Cline, Gemini CLI, a cron job, or you at a terminal all operate the same store through the same files.

A store is an ordinary git repository: markdown notes joined by [[wikilinks]], with contexture.yaml as the single source of truth for how that particular store is shaped — its taxonomy and its paths. ctxr is a mechanism-only CLI over it — it builds indexes, enforces invariants, and performs validated writes, but it makes no editorial decisions. The judgment lives in skills: portable markdown decision procedures that ctxr init installs into the store, which whatever agent you're talking to reads and follows. That split is the whole design, and it's what makes the same store operable from any harness.

Install

npm install -g ctxr-cli

Requires Node 22.13 or newer.

The package is ctxr-cli, the command it installs is ctxr, and the project is Contexture — which is why a store’s own files keep the full name (contexture.yaml, .contexture/, CONTEXTURE). A contexture alias executable is installed too; docs and generated files always say ctxr.

Running an agent harness in a container? contexture-images publishes harness runtimes with ctxr already installed — currently ghcr.io/ayxuerui/contexture-hermes, tagged by the ctxr version it carries. Nothing here depends on it; ctxr itself is distributed only through npm.

Quickstart

mkdir my-store && cd my-store
ctxr init
ctxr adapters generate   # writes the harness entry file (CLAUDE.md) and its permission config

ctxr init asks two questions, then creates the git repository (if there isn't one), scaffolds the store, and commits it:

• Which taxonomy profile? para (Projects / Areas / Resources / Archives — the default), zettelkasten (no layers at all; structure emerges from links), or diataxis (Tutorials / How-to / Reference / Explanation). Or bring your own layer list with --taxonomy <file.yaml.
• Which agent harnesses? claude-code (default — its adapter generates CLAUDE.md plus a .claude/settings.json wiring up the write-gate hook) and/or hermes-agent (reads AGENTS.md directly, so it needs no entry file at all). --harness none opts out.

Harness adapter output is the one part init doesn't write itself, which is why ctxr adapters generate is a separate line above; ctxr update regenerates it from then on.

Non-interactively, pass them as flags — nothing ever blocks on a prompt:

ctxr init --profile para --harness claude-code

init is idempotent. Re-running it against an existing store reconciles it instead (the same code path as ctxr update) rather than overwriting anything.