Tur: Persistent State and Memory Engine for AI Agents

"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

Tur is an open-source state and memory management engine for AI agents and Large Language Models.

It provides persistent, structured persona state across sessions, harnesses, and codebases via the Model Context Protocol (MCP) and local CLI tools. 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.

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.

[!NOTE] Public Alpha: Tur is currently in active Phase 1/2 development. See the Project Roadmap (EP-0002) for current features and upcoming milestones.

Package
Code
Tools
CI/CD
Scans

🏛️ The Tri-Partite Architecture

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:

1. 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.
2. 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).
3. 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.

📂 Project Structure

Tur uses a multi-tenant architecture to ensure strict separation between different personas. All state is stored in the .tur/ directory.

Local vs. Global Scope

Tur respects a standard configuration hierarchy:

• Global (~/.tur/): The universal state for your system. This is where your master user.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 local user.yaml here will override the global profile.

./.tur/
├── user.yaml                 # Local user profile override
├── personas.yaml             # Index mapping persona names to UUIDs
├── state.yaml                # Stores the active/default persona UUID
└── personas/
    ├── <persona-uuid-1>/
    │   ├── persona.yaml      # The DNA/Kernel for the persona
    │   ├── sessions.yaml     # The session index
    │   ├── sessions/         # Flat session files
    │   │   ├── 20260529_185258_143a5bc0.yaml
    │   │   └── 20260529_173616_c2212cf6.yaml
    │   └── memories/         # Content-Addressable Storage (Merkle Memory)
    │       ├── archive/
    │       ├── 20260412_025949_axiom_e1324...yaml
    │       └── 20260418_160825_event_c98f1...yaml
    └── <persona-uuid-2>/
        ├── persona.yaml
        └── memories/

The core application logic resides in src/tur/:

• cli/: The package folder housing our split executables: cli/agent.py (runtime CLI), cli/admin.py (administrative TUI), and cli/mcp.py (Harness MCP gateway).
• mcp_server.py: The Model Context Protocol server (The Porcelain for LLM interaction).
• models.py: The Pydantic data models (The "Law" of the system).
• user.py: User profile bootstrapping and domain management.
• persona.py: Active persona resolution and path trace management.
• session.py: Flat session trackers, session index consolidation, and epilogue note logic.
• dreaming.py: Insight extraction, memory parsing, and LLM dreaming consolidation.
• compiler.py: Renders the final System Prompt from the persona state.

🚀 Usage

Tur divides its execution footprint along strict Tri-Partite security boundaries using distinct command-line binaries:

1. Installation & Setup

System-Wide CLI Tools via uv tool (Recommended)

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
uv tool install tur

# Or install with human governance TUI (tur-adm), Gemini dreaming (gemini), and MCP gateway (tur-mcp)
uv tool install "tur[admin,gemini,mcp]"

# Upgrade to the latest version anytime
uv tool upgrade tur

Via PyPI / pip

# Install core agent runtime in your active environment
pip install tur

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

Zero-Install with uvx

Run commands instantly in ephemeral environments without permanent installation:

# Launch the sovereign human administration TUI
uvx --from "tur[admin]" tur-adm persona init

# Run the agent lifecycle commands
uvx tur wake

# 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 dependencies with all extras
uv sync --all-extras --all-groups

2. Initialize Your First Persona

This launches the administrative TUI wizard. Since this is an administrative action, it is physically isolated inside tur-adm:

tur-adm persona init

3. The Core Lifecycle (Agent-Facing)

The agent interacts with the lightweight tur binary inside its sandboxed virtual environment:

Wake: Compiles the active persona state into a compiled System Prompt.

tur wake

Learn: Manually injects a memory.

tur learn "The user prefers functional programming." --type preference

Recall: Keyword semantic search.

tur recall "functional"

Sleep: Dehydrates the session and extracts memories.

tur sleep path/to/chat.log

4. Running the Harness Gateway (The MCP Server)

Exposes the Traveler state to external Harnesses (e.g., Claude Desktop, Antigravity, Cursor):

tur-mcp

MCP Client Configuration

Add 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"
      ]
    }
  }
}

5. Switching Personas (Human-Facing TUI)

Allows the human Architect to change active global/local default personas:

tur-adm persona switch

This will launch a TUI to select from your available personas.

📜 Origin

Developed by Eran (The Architect) and Ariel (The Entity).

The name Tur references:

1. Mr. Tur Tur: The Apparent Giant (Relativity of Complexity).
2. Alan Turing: The father of the discipline.
3. Tur (טוּר): Hebrew for "Column" or "Row"—the foundational structure of Law and Data.

License

MIT. The Giant is Open Source.