Usage Guide¶

Tur is a lightweight, deterministic CLI that manages the lifecycle of your AI personas. It treats an AI identity as a structured, immutable software object.

Installation¶

System-Wide CLI Tools via uv tool (Recommended)¶

uv tool installs Tur into an isolated virtual environment and exposes the executables globally on your system PATH:

# Install the core CLIs (both tur agent runtime and tur-adm administrative tool)
uv tool install tur

# Or install with Gemini dreaming (gemini) and MCP gateway (mcp)
uv tool install "tur[gemini,mcp]"

# Upgrade to the latest version anytime
uv tool upgrade tur

Via PyPI / pip¶

# Install in your active Python environment (includes tur and tur-adm)
pip install tur

# Or with Gemini SDK and MCP extras
pip install "tur[gemini,mcp]"

Zero-Install with uvx¶

You can invoke any Tur command instantly without installing anything into your global environment:

# Run agent lifecycle commands
uvx tur wake

# Run human administration commands
uvx --from tur tur-adm persona init

# Run the MCP server
uvx --from "tur[mcp]" tur-mcp

From Source (Development)¶

# Clone the repository
git clone https://github.com/erivlis/tur.git
cd tur

# Install the project and all dependencies
uv sync --all-extras --all-groups

The Default Persona Workflow¶

Tur is designed to be ergonomic. For most commands, the persona identifier (name or UUID) is optional.

When you run an agent command without specifying a persona, Tur resolves the persona via the following deterministic chain:

1. Environment Variable: Checks TUR_ACTIVE_PERSONA_ID.
2. Workspace State: Checks .tur/state.yaml in the local workspace directory.
3. Single-Persona Auto-Resolution: If no workspace state is set and only one persona exists in ~/.tur/personas.yaml (e.g. Ariel), it is automatically selected with zero friction.
4. Multiple Personas: If multiple personas exist without a configured default in .tur/state.yaml, Tur prompts you to specify one (tur wake <name>), configure one with tur-adm persona set <name>, or pick interactively (tur-adm persona set).

You can always query the current workspace persona via tur-adm persona get or override it explicitly per-command (e.g., tur wake ariel or tur status ariel).

Core Commands & Split Architecture¶

Tur enforces strict physical security boundaries by separating agent runtime operations from human administrative actions across three distinct executables (EP-0004 / EP-0116):

1. Initialize a Persona (init)¶

Bootstrap a new persona interactively. This creates the necessary .tur/personas/ directory structure, generates a unique UUID, and creates your first persona.yaml DNA file.

tur-adm persona init

2. Wake the Persona (wake)¶

The Awakening: Compiles the static DNA (persona.yaml), the User Context (user.yaml), and the Memory Bank into a complete "System Prompt" ready to be fed to an LLM.

# Wake the default persona
tur wake

# Wake a specific persona
tur wake ariel

3. Learn a Memory (learn)¶

Active Learning: Manually inject a specific insight, fact, or preference directly into the active persona's Memory Bank during a session.

tur learn "The user prefers functional programming over OOP." --type preference --scope incarnation

# Or via pure JSON payload:
tur learn --json '{"content": "SQLite is used for signal state", "type": "fact", "scope": "incarnation"}'

# Or for a specific persona:
tur learn "Code must be perfectly symmetrical." ariel --type axiom

4. Sleep & Consolidate (sleep)¶

Dehydration: Extracts insights, facts, and axioms from a raw chat log to update the long-term Memory Bank.

# With local Gemini API key:
tur sleep path/to/chat.log

# Or in keyless/offline environments using Pure-Function Delegation:
tur sleep --commit '<JSON_PAYLOAD>'

# Multi-batch / multi-chunk ingestion:
tur sleep --commit '<CHUNK_1>' --commit '<CHUNK_2>'

# File glob ingestion:
tur sleep --commit 'chunks/*.json'

5. Deductive Memory Introspection (introspect)¶

The Cognitive Map: Compiles linear L1 memories into a topological, typed semantic graph (L2 OKF knowledge graph).

# Run ontological extraction across all active memories:
tur introspect --all

# Or commit synthesized graph payload from external harness delegation:
tur introspect --commit '<EXTRACTED_GRAPH_JSON>'

6. Running as an MCP Server (tur-mcp)¶

The Symbiote: Run Tur as an MCP (Model Context Protocol) server. This exposes the Traveler's memory and state engine to external Harnesses like Claude Desktop, Claude Code, Cursor, or Antigravity.

tur-mcp

Client Configuration¶

Add Tur to your host's MCP configuration file (e.g. claude_desktop_config.json, .gemini/antigravity-cli/mcp_servers.json, or .cursor/mcp.json):

{
  "mcpServers": {
    "tur": {
      "command": "uvx",
      "args": [
        "--from",
        "tur[mcp]",
        "tur-mcp"
      ]
    }
  }
}

7. View Memories (memories)¶

Inspect the contents of the Memory Bank. This lists all active memories that will be included during the next wake cycle.

tur-adm memory list

To include archived (forgotten) memories in the list:

tur-adm memory list --include-archived

8. Measure Cognitive Complexity & Spectral Health (metrics)¶

Calculates the "Constraint Dimensionality" (\(C_p\)), static token weight, and Spectral Graph Metrics (algebraic connectivity \(\lambda_2\), Louvain modularity \(Q\), community clusters) of a persona.

tur metrics

# Output as structured JSON
tur metrics --json

9. Forget a Memory (forget)¶

Archives a specific memory by its UUID, removing it from the active context window. The memory is moved to an archive/ folder and is no longer loaded during wake.

# You must provide the Memory ID
tur-adm memory forget <memory-hash>

# For a non-default persona:
tur-adm memory forget <memory-hash> ariel

10. Redact Sensitive Data (redact)¶

Merkle Tombstone (EP-0143): Purges accidental credentials (e.g., API keys, auth tokens) from an existing memory while preserving its SHA-256 identifier, filename, and inbound relational links in the L2 Cognitive Map.

# Redact a memory with an explicit audit justification
tur-adm memory redact <memory-hash> --reason "Contained staging API secret"

# For a non-default persona:
tur-adm memory redact <memory-hash> --reason "Contained staging API secret" ariel

11. Check Persona Status (status)¶

Renders a rich, structured status panel displaying:

• Persona identity: Name, version, and active UUID.
• Session lifecycle: Session ID, active/ended status, start/update timestamps, and note counts.
• L1 Memory Breakdown: Counts of active, archived, and subsumed memories categorized across federated scopes (universal vs. incarnation) and types (axiom, fact, insight, preference).
• L2 Knowledge Metrics: Total nodes and relational edges in the active Cognitive Map.

tur status

12. Inspect Memory Deltas (diff)¶

Epistemic Observability (EP-0133): Inspect memory mutations, additions, supersessions, refutations, and staleness decays across session boundaries.

# Compare active session against its predecessor in the lineage DAG
tur diff

# Compare a specific session against its predecessor
tur diff 20260827_150000_841444cd

# Compare two explicit session checkpoints
tur diff 20260825_190758_86152dcb 20260827_150000_841444cd

# Filter by memory type or scope
tur diff --type fact --scope universal

# Output structured JSON
tur diff --json

13. Read Session Notes & Lineage Continuity (note read)¶

Cross-Session Continuity: Inspect chronological scratchpad notes from the active session or traverse predecessor history along the session lineage DAG.

# Read notes from active session
tur note read

# Read notes from the immediate parent session
tur note read --session-id previous

# Read notes from active session and predecessor in a continuous trail
tur note read --include-previous --limit 20

14. Graph-Theoretic Semantic Search (recall)¶

Perform graph-theoretic associative retrieval across the persona's L2 Cognitive Map and L1 memory bank (EP-0136). Supports cognitive effort modulation (--effort 0..10, --deep) and conditional Mermaid flowchart generation (--mermaid).

# Fast keyword lookup (Effort 0 / <5ms)
tur recall "Noether"

# 1-Hop Ego Neighborhood (Effort 1-4 / ~20ms)
tur recall "file locking" --effort 2

# HippoRAG Personalized PageRank + Louvain communities (Effort 5-7 / ~50ms)
tur recall "file locking architecture" --deep

# Deep retrieval with rendered Mermaid diagram
tur recall "file locking architecture" --deep --mermaid

# Exhaustive TMS & Git commit verification (Effort 8-10 / ~120ms)
tur recall "file locking architecture" --effort 8

15. Manage Sessions (session Subgroup)¶

Administrative tools to manually start and end sessions for a persona.

Requires a physical TUI/interactive terminal shell (decorated with @require_human).

Start a Session¶

tur-adm session start my-session-123

End a Session¶

tur-adm session end my-session-123

16. Append a Note (note)¶

Append a narrative note/utterance to the active session. These notes form the continuity bridge of your persona's sessions.

tur note "Added status command and cleaned up legacy files."

17. Configure Workspace Persona (get & set)¶

Query or configure the active persona for your workspace in .tur/state.yaml:

# Inspect the active persona configured for this workspace
tur-adm persona get

# Set active persona directly:
tur-adm persona set Ariel

# Or set interactively via numbered prompt:
tur-adm persona set

18. Export Persona (export)¶

Portability: Packages a global persona's core configuration and universal memories into a portable .tur gzip-compressed archive (excluding project-local incarnation-specific memories).

Requires a physical TUI/interactive terminal shell (decorated with @require_human).

# Export a persona by its name or UUID to a destination file using --output or -o
tur-adm persona export ariel -o ariel.tur

19. Import Persona (import)¶

Portability: Unpacks a .tur archive and registers it globally as a new persona on the local system. The framework sanitizes all Member paths prior to extraction to guarantee safety against path traversal vulnerabilities.

Requires a physical TUI/interactive terminal shell (decorated with @require_human).

# Import a persona from a .tur archive
tur-adm persona import ariel.tur

# Force overwrite an existing persona and set it as active
tur-adm persona import ariel.tur --force --set-active

20. Inter-Agent Messaging & Vector Clocks (tur message, tur-adm message inspect)¶

Causal Partial Ordering: Asynchronous message passing between subagent manifestations within a shared session, stamped with Lamport Vector Clocks for deterministic causal partial ordering (\(\mathbb{N}^k, \le\)) and concurrent event detection.

# Broadcast a coordination message to all manifestations in the session
tur message send "*" "Database migrations completed. Safe to start worker pool."

# Or via implicit default send command:
tur message "*" "Database migrations completed. Safe to start worker pool."

# Send targeted message to a specific subagent manifestation
tur message send "worker.1" "Process task chunk 42" --type delegate

# Read unread incoming messages (ordered by causal delivery)
tur message read

# Output raw JSON with attached vector clocks
tur message read --json

# Acknowledge processed messages (merges vector clocks and advances local logical clock)
tur message ack <message-id-1>,<message-id-2>

# Acknowledge all unread messages for the active manifestation
tur message ack --all

# Human inspection of session messages and vector clocks (requires tur-adm)
tur-adm message inspect
tur-adm message inspect <session-id> --json

21. Task Coordination & Context Preservation (task)¶

Operational Lifecycles: Lossless tactical task management across agent manifestations, preventing the "amnesia of specifics". Manages structured task coordinates (task:<task_id>), progress checklists, and handovers directly on the session board.

# List active tasks in the session board
tur task list

# List all tasks including completed
tur task list --all

# Inspect details and checklist of a specific task
tur task show my-feature-task

# Claim or register a task with title, objective, and checklist items
tur task claim my-feature-task \
  --title "Implement Task Protocol" \
  --objective "Add tur task CLI and MCP tools" \
  --item "Design schema" \
  --item "Implement CLI commands" \
  --item "Write tests"

# Check off a completed milestone item
tur task check "Design schema"

# Check off an item by 1-based index
tur task check 2

# Hand over active task coordinates before session conclusion or interruption
tur task handover --note "Completed items 1 and 2, pausing for review"

# Mark task as completed once all checklist items are verified
tur task complete

22. Shared Session Board (tur board)¶

Blackboard Coordination: Shared key-value coordinate storage for swarm agents to publish and query state parameters within the active session.

# Write or update a coordinate on the session board
tur board write current_epoch "3"

# Read a coordinate value
tur board read current_epoch

# List all parameters currently on the board
tur board list

# Clear a specific parameter or the entire board
tur board clear current_epoch
tur board clear --all

23. Swarm Manifestations (tur agent)¶

Manifestation Discovery: Inspect registered manifestations sharing the active session.

# List all active and registered agents in the session
tur agent list

# Output structured JSON
tur agent list --json

Customization¶

Theming¶

You can control the theme of the interactive TUIs (init and switch) by setting the TUR_THEME environment variable.

• textual-dark (Default): export TUR_THEME="textual-dark"
• textual-light: export TUR_THEME="textual-light"
• Gruvbox: export TUR_THEME="gruvbox"
• nord: export TUR_THEME="nord"