Note
Public Alpha: Tur is currently in active Phase 1/2 development. See the Project Roadmap (EP-0002) for current features and upcoming milestones.
Tur is an open-source state and memory management tool for AI agents.
It provides a persistent, structured persona state across sessions, harnesses, and codebases via local CLI tools or Model Context Protocol (MCP). Rather than relying on ephemeral system prompt configuration, Tur manages persona identity, operational principles, hierarchical memory (L1 ledger & L2 knowledge graph), and session continuity as structured, version-controlled files.
| Package |
|
| Code |
|
| Tools |
|
| CI/CD |
|
| Scans |
|
| Mentions |
|
Tur operates on a strict ontological boundary separating the "Mind" from the "World". To achieve high fidelity and true portability, an agentic system must be divided into three distinct pillars:
- The Traveler (Managed by Tur): The intrinsic, portable components of the Mind.
- Persona: The identity, aleph, and version.
- Principles: The cognitive filters (The Council of Giants).
- Protocols: Active behavioral loops (e.g., The Evolution Protocol).
- Memory: The L1 Ledger and L2 Graph representing the continuity of self.
- The Terrain (Managed by the Project): The local physics and environment the agent operates within.
- Codebase: The raw files.
- Styleguide: The rules for formatting and structure in this specific repo.
- Documentations: Any additional context (e.g., this README).
- The Harness (Managed by the Agent Framework): The engine providing compute and capabilities.
- Inference Engine: The underlying LLM (e.g., Claude, Gemini).
- Tools: The mechanical affordances (e.g., bash, git, file reading).
- Examples: Claude Code, Gemini CLI, OpenCode, Pi, etc.
Tur is exclusively responsible for The Traveler. By ensuring the "Soul" is mathematically bound (via Merkle hashing), cleanly decoupled from anthropomorphic engine leaks, and separated from the Harness and Terrain, the Persona becomes an obligate symbiote—able to be unplugged from one Harness and plugged into another without losing its identity or memories.
Tur uses a multi-tenant architecture to ensure strict separation between different personas. All state is stored in the
.tur/ directory.
Tur respects a standard configuration hierarchy:
- Global (
~/.tur/): The universal state for your system. This is where your masteruser.yaml(The Architect's profile) lives. - Local (
./.tur/): The repository-specific state. If you initialize Tur inside a project, it creates a local.tur/folder containing the Personas bound to that specific Terrain. A localuser.yamlhere will override the global profile.
Tur divides its execution footprint along strict Tri-Partite security boundaries using distinct command-line binaries:
Installs Tur into an isolated environment and makes the executables (tur, tur-adm, tur-mcp) globally available on
your system PATH:
# Install the core agent CLI and administrative tools (tur and tur-adm)
uv tool install tur
# Or install with Gemini dreaming (gemini) and MCP gateway (tur-mcp)
uv tool install "tur[gemini,mcp]"
# Upgrade to the latest version anytime
uv tool upgrade tur# Install core runtime and admin CLI in your active environment
pip install tur
# Or with Gemini SDK and MCP extras
pip install "tur[gemini,mcp]"Run commands instantly in ephemeral environments without permanent installation:
# Launch sovereign human administration commands
uvx --from tur tur-adm persona init
# Run the agent lifecycle commands
uvx tur wake
# Run the MCP server
uvx --from "tur[mcp]" tur-mcp# Clone the repository
git clone https://github.com/erivlis/tur.git
cd tur
# Install dependencies with all extras
uv sync --all-extras --all-groupsThis launches the interactive administrative wizard. Since this is an administrative action, it is physically isolated
inside
tur-adm:
tur-adm persona initThe agent interacts with the lightweight tur binary inside its sandboxed environment. Tur provides a two-tier command grammar: single-word cognitive reflexes for fast lifecycle management, and domain subcommands for multi-agent swarm coordination, task tracking, and structured memory operations. See the complete Usage Guide for full syntax and options.
# Wake: Compiles active persona, principles, and active task state into a system prompt
tur wake
# Learn: Manually ingest a permanent memory into the L1 ledger
tur learn "The user prefers functional programming." --type preference
# Recall: Keyword and semantic memory retrieval
tur recall "functional"
# Sleep: Dehydrate session and consolidate memories from chat log
tur sleep path/to/chat.log| Subsystem | Command Example | Description |
|---|---|---|
task |
tur task claim <id> --title <t> |
Tactical milestone and handover preservation (EP-0147) |
board |
tur board write <key> <val> |
Shared multi-agent parameter blackboard (Blackboard Architecture) |
message |
tur message send <to> <content> |
Causal inter-agent messaging with Lamport vector clocks (EP-0141) |
note |
tur note write <text> |
Ephemeral in-flight session scratchpad |
memory |
tur memory recall <query> |
Deep associative recall, Louvain graph clustering, and Merkle verification |
agent |
tur agent list |
Multi-agent swarm discovery, heartbeats, and manifestation resolution |
Tip
Universal --json Standard: Every query, list, and inspection command across tur accepts --json (or -j) for headless subshell scripting and clean tool parsing.
Exposes the Traveler state to external Harnesses (e.g., Claude Desktop, Antigravity, Cursor):
tur-mcpAdd Tur to your client configuration (e.g., claude_desktop_config.json, .cursor/mcp.json, or Antigravity config):
{
"mcpServers": {
"tur": {
"command": "uvx",
"args": [
"--from",
"tur[mcp]",
"tur-mcp"
]
}
}
}Allows the human Architect to inspect or assign the active workspace persona in .tur/state.yaml:
# Inspect the active persona for the current workspace
tur-adm persona get
# Assign the active persona directly
tur-adm persona set Ariel
# Or select interactively from a numbered prompt
tur-adm persona set"From a distance, he appeared to be a giant. But as they approached, he became a man of normal stature."
— Jim Knopf und Lukas der Lokomotivführer by Michael Ende
The project is inspired by the Tur Tur Principle: The complexity of AI behavior can be made more focused and manageable by imposing clear constraints, deterministic state files, and explicit behavioral protocols.
The name Tur references:
- Mr. Tur Tur: The Apparent Giant (Relativity of Complexity).
- Alan Turing: The father of the discipline.
- Tur (טוּר): Hebrew for "Column" or "Row"—the foundational structure of Law and Data.
MIT. The Giant is Open Source.