Reference

The operational reference for the temper CLI, cloud sync, and MCP server. For the conceptual frame — what Temper is, and why — start with cognitive maps, or read the commitments in theory.

Install

macOS (Apple Silicon) and Linux (x86_64):

curl -fsSL https://raw.githubusercontent.com/tasker-systems/temper/main/scripts/install/install.sh | sh

Windows (x86_64, PowerShell):

irm https://raw.githubusercontent.com/tasker-systems/temper/main/scripts/install/install.ps1 | iex

Windows support is experimental in the 0.1.x line — file issues at github.com/tasker-systems/temper/issues if you hit problems.

To pin a version, pass --version vX.Y.Z to the install script. See docs/guides/install.md for uninstall instructions and Linux arm64 / Intel Mac notes.

Build from source

If you'd rather compile locally (Intel Mac, Linux arm64, or just to hack on temper itself):

git clone https://github.com/tasker-systems/temper.git
cd temper
cargo install --path crates/temper-cli --features embed,extract,hnsw

The embed feature pulls in ONNX Runtime for local embeddings; extract enables document ingestion via kreuzberg; hnsw enables the local vector index. Drop any you don't need.

Getting started

The local vault is a directory of markdown files with YAML frontmatter — a read-only projection of cloud state, not the source of truth (see Cloud). Temper resolves its config from ~/.config/temper/config.toml or a per-project .temper/config.toml.

`temper init`	Initialise a new vault — asks how you work, writes config.
`temper context add <name>`	Subscribe to a context (project). Contexts keep resources scoped.
`temper warmup --context <ctx>`	Session primer — recent work, open tasks, recent decisions. Pipe into an agent's first prompt.
`temper pull <ctx>`	Re-materialise a context's projection from the cloud into the local vault.
`temper status`	Vault overview: contexts, resource counts, recent activity.
`temper check`	Verify vault integrity and tool health.

To add content, create a resource and pipe in a body — temper resource create --type research --title "…" --body @notes.md. See Resources.

Resources

Every piece of knowledge in temper is a resource — a markdown file with typed frontmatter. Six doc types cover the vocabulary of structured work:

`goal`	Outcome — what we're building.
`research`	Survey of alternatives, constraints, prior art.
`decision`	What we chose, and why.
`task`	Unit of work — what comes next.
`session`	What happened — record of a working session.
`concept`	Shared vocabulary within the vault.

Resources are addressed by ref — a UUID, or the decorated slug-<uuid> form (resolved by the trailing UUID; the slug half is presentation, so a stale slug is harmless). Every list / show / search row prints a ref field — copy it, paste it.

Create · list · show · update · delete

`temper resource create --type <t> --title <title>`	Create a resource. Add `--body @file.md` (or pipe markdown via stdin) for content; `--context`, `--goal`, `--mode`, `--effort` as needed.
`temper resource list --type <t>`	List resources of a type (`--type` is required). Filters: `--context`, `--stage`, `--goal`, `--limit`; `--meta-only` / `--fields` for cheaper reads.
`temper resource show <ref>`	Show a resource by ref. Add `--edges` for its graph edges, or `--meta-only` for frontmatter without the body.
`temper resource update <ref> --title <t>`	Update the title. (Body: `--body @file.md` or pipe markdown via stdin.)
`temper resource update <ref> --context-to <ctx>`	Move the resource to a different context.
`temper resource update <ref> --stage <s>`	Task stage: `backlog`, `in-progress`, `done`, `cancelled`.
`temper resource update <ref> --mode <m>`	Task mode: `plan`, `build`.
`temper resource update <ref> --effort <e>`	Task effort: `small`, `medium`, `large`.
`temper resource update <ref> --relates-to <ref>`	Add a relationship. Repeatable. Similar: `--references`, `--depends-on`, `--extends`, `--preceded-by`, `--derived-from`.
`temper resource update <ref> --branch <name> --pr <url>`	Task metadata: attach a git branch or PR URL.
`temper resource delete <ref>`	Soft-delete on the server (the authoritative action; the row is preserved server-side). `--force` is accepted but vestigial — deletion is non-interactive.

Search

temper search combines full-text and semantic search with optional graph expansion — seeds spread along typed edges to surface neighbors.

`temper search <query>`	Hybrid search across the vault.
`--context <ctx>`	Scope to one context.
`--doc-type <type>`	Filter by doc type.
`--limit <n>`	Cap results (default 10).
`--text-only`	Skip semantic search (no local embedding needed).
`--seed <uuid>`	Explicit seed resource for graph expansion. Repeatable.
`--edge-type <kind>`	Restrict graph expansion to one or more edge kinds. Repeatable.
`--depth <n>`	Max hops for graph traversal (default 2, max 10).

Relationships

Resources aren't isolated — typed edges connect them, and search can expand along those edges to surface neighbors. Edges are first-class: asserted explicitly, then re-typed, re-weighted, or folded as the understanding changes. Source and target are refs; an edge is addressed by its own handle (a UUID).

`temper edge assert <source> <target> --kind <k> --polarity <p> --label <text>`	Assert a typed edge. Kinds: `express`, `contains`, `leads-to`, `near`. Polarity: `forward` or `inverse`. Optional `--weight` (default 1.0). Idempotent.
`temper edge retype <edge-handle> --kind <k> --polarity <p>`	Change an edge's kind and polarity.
`temper edge reweight <edge-handle> --weight <n>`	Change an edge's weight.
`temper edge fold <edge-handle> [--reason <text>]`	Fold (supersede) an edge — it stops contributing to projections, with the reason recorded.

Cloud

Temper Cloud is the Postgres-native source of truth, with pgvector-powered semantic search. The local vault is the inverse of the old model: a read-only projection cache, not the canonical copy. Writes (resource create/update/delete, edge) route straight to the API and take effect immediately; temper pull <ctx> re-materialises the local markdown from server state. Removing a projected file with rm is just a local cache miss — it has no server effect.

Auth

`temper auth login`	Browser-based OAuth with PKCE. Caches the token locally.
`temper auth status`	Show current auth state.
`temper auth logout`	Clear cached credentials.
`temper auth token`	Store a JWT directly (for API-only clients or manual auth).
`temper auth export-token`	Print the cached JWT to stdout — pipe into a cloud session's secret manager as `TEMPER_TOKEN`.

Teams

`temper team join`	Request to join a team — `--team` to name it, `--message` to attach a note.
`temper team status`	Check request or membership status.
`temper team leave`	Withdraw a pending request or leave a team.

Agents

Temper is built to be legible to AI coding agents. Two integration paths — a Claude Code skill file, or the remote MCP server.

Claude Code skill

A skill file teaches an agent your vault's structure, doc types, and workflow vocabulary. Temper generates one tailored to your vault:

temper skill install

`temper skill install`	Install skill directory and command wrapper.
`temper skill generate`	Preview the skill content to stdout without installing.
`temper skill check`	Report installation status.

To automatically prime new Claude Code sessions with recent context, add a SessionStart hook:

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "temper warmup --context myapp"
      }]
    }]
  }
}

MCP server

The remote MCP server exposes vault operations as structured tools over Streamable HTTP. Agents authenticate via Auth0 using the OAuth 2.1 + PKCE flow. Connect Claude Desktop or Claude Code:

{
  "mcpServers": {
    "temper": {
      "url": "https://temperkb.io/mcp"
    }
  }
}

The client handles OAuth automatically — you'll be prompted to log in on first connection.

Available tools

`list_resources`	List resources, filtered by context and/or doc type. Most recent first.
`get_resource`	Get a resource by ID or slug, optionally with full markdown content.
`create_resource`	Create a resource with optional markdown content. Name-based context and doc type.
`update_resource`	Update a resource's title, slug, or content. New content triggers re-indexing.
`update_resource_meta`	Update a resource's managed/open frontmatter without touching the body.
`delete_resource`	Soft-delete a resource by ID.
`assert_relationship`	Assert a typed edge between two resources. Idempotent.
`retype_relationship`	Change an edge's kind and polarity.
`reweight_relationship`	Change an edge's weight.
`fold_relationship`	Fold (supersede) an edge so it stops contributing to projections.
`search`	Full-text and semantic search across the knowledge base.
`list_contexts`	List available contexts (workspaces).
`get_context`	Get details of a specific context.
`create_context`	Create a new context (workspace).
`list_doc_types`	List available document types.
`describe_doc_type`	Describe a doc type's schema — required and optional frontmatter fields.
`list_events`	List events, optionally filtered by resource or type.
`get_profile`	Get the authenticated user's profile.

Config

Global config lives at ~/.config/temper/config.toml. A per-project .temper/config.toml overrides it when temper is run from that directory.

`temper config edit`	Open config.toml in `$EDITOR` — validate-then-save semantics.
`TEMPER_VAULT=<path>`	Env var override for the vault path. Also accepted as `--vault <path>` on any command.

← Back to home