Docs

Temper gives your work a throughline — the connective thread across sessions, decisions, and evolving understanding. Everything resolves to markdown.

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

A vault is a directory of markdown files with YAML frontmatter. 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 add <path> --context <ctx>`	Import a file, URL, or directory into the vault. Extracts markdown and adds frontmatter.
`temper add <path> --dir --context <ctx>`	Import every file in a directory.
`temper warmup --context <ctx>`	Session primer — recent work, open tasks, recent decisions. Pipe into an agent's first prompt.
`temper status`	Vault overview: contexts, resource counts, recent activity.
`temper check`	Verify vault integrity and tool health.
`temper doctor`	Validate frontmatter across the vault; repair drift.
`temper events`	Show recent vault events.

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.

Create · list · show · update

`temper resource create --type <t> --title <title>`	Create a new resource of any type.
`temper resource list`	List all resources across types and contexts.
`temper resource list --type task`	Filter by type (goals show task stage counts).
`temper resource show <id>`	Show a resource. Accepts slug, slug suffix, or task sequence number.
`temper resource update <id> --title <t>`	Update the title.
`temper resource update <id> --context-to <ctx>`	Move the resource to a different context.
`temper resource update <id> --stage <s>`	Task stage: `backlog`, `in-progress`, `done`, `cancelled`.
`temper resource update <id> --mode <m>`	Task mode: `plan`, `build`.
`temper resource update <id> --effort <e>`	Task effort: `small`, `medium`, `large`.
`temper resource update <id> --relates-to <slug>`	Add a relationship. Repeatable. Similar flags: `--references`, `--depends-on`, `--extends`, `--preceded-by`, `--derived-from`.
`temper resource update <id> --branch <name> --pr <url>`	Task-specific metadata: attach a git branch or PR URL.

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 <id>`	Explicit seed resource for graph expansion. Repeatable.
`--depth <n>`	Max hops for graph traversal (default 2, max 10).
`--no-graph`	Disable graph expansion.

Knowledge graph

Resources aren't isolated — frontmatter references (relates_to, depends_on, etc.) form a graph. Two commands populate it:

`temper graph build`	Scan markdown bodies for references and seed the frontmatter relationships. Additive — doesn't overwrite existing edges.
`temper graph build --dry-run`	Preview edges without writing.
`temper graph index`	Discover concepts via LLM judgment over the local HNSW index. Requires `temper index` to have been run first.
`temper index`	Build the HNSW vector index over the vault. Needed for semantic search and the graph concept-discovery pass.
`temper index --full`	Force a full rebuild.

Cloud sync

Temper Cloud is a Postgres-native source of truth for your vault with pgvector-powered semantic search. Your local markdown files remain canonical — the cloud is a searchable, syncable lens on them.

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).

Sync

Sync uses a manifest-based three-way compare between your local file, a manifest record, and the server. Non-conflicting changes auto-merge at the paragraph level; genuine conflicts are written to .conflict.md for human resolution.

`temper sync run`	Run a full sync cycle — push local changes, pull remote ones.
`temper sync run --context <ctx>`	Sync only one or more contexts.
`temper sync status`	Show what would change, without making changes.
`temper sync refresh`	Refresh manifest from server — non-destructive interleave.
`temper sync reset`	Reset manifest from scratch (backs up first, then full rebuild).
`temper pull <resource-id>`	Pull a single resource by UUID.
`temper resource delete <slug> --type <doctype> [--force]`	Delete a resource: cloud-first soft-delete, then local cleanup tail in local mode.

Teams

`temper team join`	Request to join a team — defaults to system access.
`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.
`delete_resource`	Soft-delete a resource by ID.
`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.
`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