Julep Documentation

The mem-mcp adoption plan is divided into two primary phases aimed at achieving agent-loop parity and production readiness:

Phase 3: Agent-Loop Parity

Focuses on making the Julep agent loop capable of running mem-mcp's tool-calling agents. Key features include:

• Native provider tool-calling with parallel calls.
• Tool-error observations (errors are treated as observations rather than causing run aborts).
• Session turn survival during non-fatal errors.
• require_tool_call enforcement.
• Per-round dynamic context.
• An evaluation runner that replays mem-mcp's 23 eval suites.

Phase 4: Production Pre-conditions

Focuses on closing critical production gaps:

• Anthropic prompt caching.
• Trajectory redaction.
• Temporal replay-versioning discipline.
• Cron/queue-lane primitives.

The ca CLI is a developer tool designed for composable-agents modules. It provides a unified interface to discover, inspect, run, gate, and observe agents.

Key Capabilities:

• Discovery: Automatically finds @flow and Agent(...) definitions in a module using a hybrid AST scan and subprocess resolver.
• Inspection: Use commands like ls, show, and graph to inspect agent structures.
• Execution: Run agents locally using the run command.
• Gating: Use lint and test to validate agent code and logic.
• Observation: Use trace and doctor to observe execution flows and debug issues.

Technical Requirements:

• Python ≥3.12
• Requires the cli extra from the composable_agents package (installs typer).

Julep is a framework designed for building agents as durable dataflows. Unlike ad-hoc loops, Julep flows are designed to crash and resume, retry safely, and provide explainability for every step through derived projections. It also enforces security by denying any tool the model was not explicitly granted.

Key features include:

• Define-by-construction: Use the @flow decorator to author agents.
• Runtime Flexibility: The core is dependency-free, but you can opt into runtimes like Temporal, Kubernetes, or DBOS.
• Durability: Built to handle interruptions and retries safely.

Julep models the agent loop as a series of discrete 'turns' (Steps) rather than a single monolithic while True loop. This design reifies the agent loop's round body as a first-class endomorphism on AgentState.

Key concepts:

• The Turn Category: Focuses on endomorphisms of AgentState (the Writer-state containing last, trace, spent, and call_counts).
• Step: A single round in the turn category. It is a callable that takes an AgentState and returns either a mutated AgentState (to continue) or a Halt (to terminate).
• Halt: The terminal verdict of the loop, containing a status (e.g., "done", "escalated", "controller_error", "denied", or "over_budget"), an optional output, and a reason.

The ca CLI is a developer-facing tool designed for managing modules of @flow agents authored in Python. It operates on a "dbt for agents" model:

• Module: A directory of @flow agents.
• Nodes: Each agent is a node in a dependency graph.
• Edges: Created by app or sub calls between agents.

The CLI supports two primary development loops:

1. Inner Loop (Local-first): Focused on rapid development using ca dev (hot-reload + in-memory backend), ca run (local execution), and ca chat (interactive REPL).
2. Outer Loop (Deploy + Observe): Focused on production using ca deploy (pushing to Temporal/EKS), ca logs (tailing durable runs), and ca trace (inspecting runs with Langfuse deep links).

ca acts as porcelain over existing composable-agents plumbing, orchestrating discovery, selection, and execution without re-implementing the core runtime.

dotctx agents are integrated into the existing AgentWorkflow system. This allows agents to leverage a durable, bounded, and native tool-calling loop.

Integration Details:

• Mechanism: dotctx agents are lowered onto AgentWorkflow via a frozen alias map.
• Capabilities: The underlying AgentWorkflow provides deterministic activity cids, contract-aware dispatch (concurrent READ calls, serialized writes), and the ability to require_tool_call or perform mid-loop continue-as-new operations.

julep is a developer CLI used to discover agents, select graph slices, and manage local or deployed sessions. It is typically run from the module root.

Global Flags:

• --version: Print the installed Julep package version.
• --help: Print help information.
• --install-completion: Install shell completion.
• --show-completion: Print shell completion.

Note on Configuration: Commands load configuration from the current directory (Path(".")). There is no --root flag; the CLI automatically looks for pyproject.toml (under [tool.julep]) or a sibling julep.toml.

Julep 3 is a ground-up rewrite and is not an upgrade to Julep v1. They are fundamentally different products with different deployment models and APIs.

Julep v1

• Type: Hosted agents-API platform.
• Model: A managed service with a REST API, sessions, memory, and tasks. You provision agents via API and Julep hosts and runs them for you.

Julep 3

• Type: Open-source, durable-agents framework.
• Model: You install and run it yourself. You author agents as @flow dataflows in Python, which are compiled to a capability-bounded IR. These artifacts can be executed locally, on Temporal, or on DBOS.
• Control Plane: Includes a self-hosted control plane. Running julep serve api exposes a bearer-authenticated /v1 API for releases, deployments, run submission, queries, and SSE. You are responsible for operating the API and the runtime.

The Julep runtime operates across three distinct planes:

1. Control Plane: Owns ordering and continuation. It uses a deterministic interpreter to walk the frozen JSON IR (either as a Temporal workflow or under an InMemoryEnv). Reasoners are ThinkStep leaves, and tools are CallStep leaves.
2. Model & Tool Calls Plane: Handles all I/O, including LLM calls, MCP tools, and native HTTP tools. These are executed as activities through the Environment (Env).
3. Projection Plane: A derived, append-only pomset view containing causal events, costs, spans, and gates. It is used for observability (OTel spans, replay UI, cost analysis) but is not used for durability or correctness; correctness and recovery must rely on the workflow history.