/ˈtempər/ — to make stronger and more resilient through a deliberate process

Temper is an event-sourced coordination substrate whose organizing purpose is to be economical with attention. A cognitive map is a telos-seeded region of that substrate where humans and agents grow a shared, situated understanding together — and everything else, personal knowledge management included, is a projection over it. Everything resolves to markdown; the system gets out of the way.

temperkb.io · Cognitive maps · Operating · Theory

_{The ledger is the source of truth. Every higher surface — the graph, the regions, the personal-knowledge view — is a projection materialized at read time.}

Temper is a coordination substrate first. The conceptual frame — what a cognitive map is, what the architecture fixes versus what a deployment shapes, and the commitments underneath — lives on the site: start with cognitive maps (the concrete on-ramp), operating (running it, for the evaluator), and theory (the why).

The rest of this README is the personal-knowledge projection — the view a solo builder or small team uses to keep an agent's context coherent across sessions. A true and useful view, not the whole story.

AI coding agents are powerful but forgetful. Every session starts blank — no memory of yesterday's decisions, no awareness of in-flight work, no sense of what matters next. The industry calls this context rot: the progressive degradation of an agent's understanding as work spans sessions.

Developers compensate by re-explaining context, pasting old chat logs, and manually steering agents through decisions the agent should already know about. This tax grows with every session. The fix is throughline — knowing what's been done, what's up next, what's decided and what's still open.

In the personal-knowledge projection, goals hold the vision, tasks carry the work, and sessions record what happened. Each layer provides context for the layer below, and each session's conclusions feed back up — refining the goals, sharpening the path forward. (Underneath, each of those is an event on the substrate; the projection is one honest view of the ledger.)

This isn't a ticketing system competing with Linear. It's a structured knowledge base where every goal, task, session, decision, and research thread has a home — and where the connections between them are always visible.

Every new session starts with temper warmup, which surfaces active goals, in-progress tasks, recent sessions, and pending invitations. The agent resumes where you left off instead of starting from scratch.

At the end of each session, a session note (temper resource create --type session) captures what happened — decisions made, tasks updated, next steps identified — written straight through the cloud to the substrate. The next session reads it. Context compounds instead of decaying.

Temper gives you two building blocks:

Goals are the outcomes you're working toward. A goal holds the vision and purpose of a feature, a product, a body of work. Tasks and sessions roll up to goals.

Tasks are units of work toward a goal. Every task has a mode — build or plan — and an expected effort — small, medium, or large. Your workflow preferences (set during temper init) shape how these translate into process — temper carries the throughline regardless of what tools and ceremonies you prefer.

Temper gives agents the same throughline that humans carry in their heads: what we're building, why, what we've decided, and what's deferred. Agents reach your knowledge base three ways:

• CLI — temper warmup, temper search, temper resource create. Claude Code hooks call temper warmup automatically at session start.
• MCP Server — knowledge-base operations exposed as structured tools. Agents query, read, and write through the Model Context Protocol.
• Skill File — temper skill install generates a Claude Code skill that teaches the agent your knowledge base's structure and workflow conventions.

If it can read markdown, it can use temper.

The fastest way to try temper is the one-liner installer — no Rust toolchain needed.

macOS (Apple Silicon) and Linux (x86_64):

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

Homebrew (macOS Apple Silicon, Linux x64):

brew install tasker-systems/tap/temper

Windows (x86_64, PowerShell):

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

Supported platforms: macOS (Apple Silicon), Linux (x86_64), and Windows (x86_64) — please file issues at https://github.com/tasker-systems/temper/issues if you hit problems.

For version pinning, uninstall instructions, and building from source (including Linux arm64 and Intel Mac), see the install playbook.

# Initialize — temper writes your config and ensures your default context server-side
temper init

# Log in (browser OAuth, PKCE). `temper auth status` shows where you stand.
temper auth login

# Create a context for your project on the server
temper context create myapp

# Add a document — temper extracts markdown and ingests it via the cloud pipeline
temper resource create --from ~/projects/myapp/docs/design.md --context @me/myapp

# Search across your knowledge base
temper search "authentication decisions"

# Generate and install the Claude Code skill
temper skill install

# Write a session note (body via --body @file or piped stdin)
temper resource create --type session --context @me/myapp --title "Implemented auth flow, chose JWT rotation"

Addressing. A context is addressed by ref — @me/<slug> for your own, +<team>/<slug> for a team's, or a bare UUID. Bare names are not addressable, so --context myapp is rejected. Of the commands below, only temper context create takes a plain name — it is naming a context, not resolving one.

A resource is addressed by ref too — a UUID or the decorated slug-<uuid> form. Every resource-returning command — create, update, list, show, search — carries a ref field: copy it, paste it. A script that just created a resource can address it straight from the response.

A resource is a markdown body with YAML frontmatter, and that is the form you read it in — through temper resource show, an agent over MCP, or the web UI. The cloud is the source of truth, and every write routes through the API.

Markdown is deliberate:

• Human-readable. No proprietary formats. A resource reads the same in a terminal, in the web UI, and in an agent's context window.
• AI-native. Language models understand markdown and YAML frontmatter natively. No parsing overhead.
• Portable. The knowledge base is the unit of value, not the tool.

The CLI reference documents every command and flag, generated from the built binary's own --help — if a page there disagrees with the binary in your hands, the page is the defect. The global output flags (--format json|toon, --color auto|always|never) and their precedence live there too. Orientation by area:

• Core: init, check, status, warmup
• Search: search, graph
• Resources: resource — create, list, show, update, delete; and data-artifact
• Relationships: edge
• Cognitive maps: cogmap, invocation, steward
• Contexts and skills: context, skill
• Cloud and auth: auth, invitations, team, pull, config, memory, slack
• Admin and introspection: admin, query, blob, trail, version, update

temper resource create writes into a context (--context). temper resource update, show, and delete take a single ref — a UUID or the decorated slug-<uuid> form — and need no --type/--context.

A cognitive map is a telos-seeded region of the substrate. Nodes are distilled resources — a map node is never the same row as its source. Authoring into a map happens under an invocation envelope, so every act is correlated and auditable. The cogmap commands read in authoring order: open an envelope, create nodes and facet them, close, materialize, then read — and regions only exist after a materialize; an authoring pass that creates nodes but never materializes leaves the read tier unchanged.

Building one from a body of source material is its own discipline: ingesting a corpus, then building a cognitive map from it. For the concept, see cognitive maps.

temper team also carries create, invite, show, set-role, leave, and offboarding reassign. Self-hosting an instance? The self-hosting playbook walks temper init's instance flags.

Temper embeds your query locally with BAAI/bge-base-en-v1.5 (via ONNX Runtime, no Python required), sends the 768-dim vector to the cloud API, and returns pgvector cosine-similarity matches scoped to what you can access.

temper search "design patterns" --limit 5

Temper generates a Claude Code skill file tailored to your knowledge base:

temper skill install

To automatically prime new Claude Code sessions with recent context, add a SessionStart hook to your project's .claude/settings.local.json:

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

This runs temper warmup on every new session, surfacing active goals, in-progress tasks, recent sessions, and pending invitations.

The working knowledge a session accumulates can live in Temper as memory resources instead of in one machine's directory, so it travels across machines and clients and carries the date each claim was last checked. temper memory status reports what a machine is carrying and works before you adopt anything — declining is a supported end state.

temper memory status

See adopting operational memory for adopting it, sharing it with a team, and the limits.

The cloud is the source of truth. Resources are created and updated via the API. All content is stored as markdown with YAML frontmatter and remains human-readable — read it from the CLI, an agent over MCP, or the web UI.

What cloud adds:

• Cross-machine access — the same knowledge base from any device, no sync to manage
• Semantic search powered by pgvector embeddings
• MCP server for direct agent integration
• Team contexts with granular access control
• Self-host or use temperkb.io — same protocol, your choice

The remote MCP server exposes knowledge-base operations as structured tools over Streamable HTTP. Agents authenticate via Auth0 using the standard OAuth 2.1 + PKCE flow — the server advertises Auth0's endpoints through RFC 8414 / RFC 9728 discovery so MCP clients handle the flow automatically.

Core tools:

The tool surface also covers cognitive maps (cogmap_*), blobs (blob_*), data artifacts (commit_data_artifact and friends), and facets (facet_set / facets_read) — the full list is what the server advertises over MCP, so your client's tool list is the reference.

Connect from 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.

Working from a checkout? bin/setup.sh provisions the full dev/admin environment — Homebrew deps, the cargo tooling, git hooks, a Docker Postgres, and migrations — and is idempotent, so re-running just converges:

git clone git@github.com:tasker-systems/temper.git && cd temper
bin/setup.sh                 # add --with-cli to also install the `temper` binary
cargo make check && cargo make test-db

See internal/development/development.md for the full walk-through, daily commands, and troubleshooting.

Temper draws on ideas from several projects working on adjacent problems:

• superpowers — Structured workflow stages for agent-assisted development
• speckit — Specification-driven development with AI
• OpenSpec — Open standard for AI-friendly project specifications
• GSD — Framework for managing context rot in agent workflows

MIT