Ori CLI

Agentic coding harness with persistent memory and a REPL body. Open source. Multi-model. Local-first.

v0.1.0-beta · Apache-2.0 · First push, April 7 2026 at 2 a.m. Documentation will be refined over the coming days. Community Discord in progress — contributions, testing, and discussion welcome.

Built on Ori Mnemos.

Quick Start

npm install -g @ori-memory/aries
ori

The harness installs Ori Mnemos as a dependency — persistent memory is included. First run walks through setup: model selection, API key configuration, optional vault connection. Sessions start immediately after.

Overview

Ori CLI is a terminal-based agent harness for software engineering. It manages the agentic loop — prompt assembly, model invocation, tool dispatch, context management, memory persistence — as a structured cognitive environment built with Ink (React for terminals).

The harness is model-agnostic. It routes to Anthropic, Google, OpenAI, DeepSeek, Moonshot, Groq, OpenRouter, Ollama, and any OpenAI-compatible endpoint, including local GGUF models served by llama.cpp. Users provide their own API keys.

Two architectural components distinguish the system:

1. A REPL body — a persistent Python subprocess with a tree-sitter-indexed graph of the codebase in memory, providing the agent with structural navigation, judgment operations, and a computational reasoning surface.

2. Native Ori Mnemos integration — persistent memory across sessions with learning retrieval, identity continuity, and a closed feedback loop between retrieval and utility.

The REPL Body

Problem

Standard coding agents interact with source code through text-oriented tools: read a file, search for a string, edit a line range. The agent perceives the codebase as a collection of flat text buffers and navigates sequentially — one file read, one grep, one edit at a time.

This sequential interaction model has a structural inefficiency. The agent cannot reason about the codebase as a whole. It cannot ask "which files are structurally central" or "does this new function duplicate existing logic" without manually reading and comparing files one by one. Each navigation step costs a full model turn — prompt assembly, inference, response parsing — regardless of whether the operation requires language model reasoning or could be resolved computationally.

Architecture

Ori CLI provides a persistent Python subprocess — the body — that maintains a tree-sitter-parsed, graph-indexed representation of the entire repository in memory. The codebase is indexed at session start using tree-sitter grammars (TypeScript, JavaScript, Python) into a rustworkx directed graph. Files are nodes. Import and reference relationships are weighted edges. The graph is re-indexed after edits to maintain consistency.

The body exposes the following operations in the REPL namespace:

Structural Analysis

Judgment Operations

Recursive Self-Invocation (rlm_call)

The body includes rlm_call — a mechanism for the agent to spawn focused sub-LLM invocations from within REPL code. The agent writes Python that calls rlm_call(question, context), which makes a plain API completion with a focused slice and returns the result as a Python value.

Depth is bounded architecturally: the sub-call receives a single user-turn prompt with no tools, no REPL, and no access to rlm_call. Its response is a string — data, not executable code. Parallel execution is supported via rlm_batch with an asyncio semaphore (default 5 concurrent). Call count is capped per top-level execution (default 15).

This enables compositional reasoning patterns: the agent decomposes a question into sub-questions, dispatches them in parallel, and synthesizes results — all within a single REPL execution, without consuming additional agentic loop turns.

Output Discipline

The harness enforces a constraint on model output: do not narrate, do not announce tool calls, do not summarize results. When the agent needs to reason, it writes Python in the REPL that reasons computationally.

The rationale is mechanical. Every output token the model spends on narration ("Let me check the file...") is a token not spent on tool calls and computation. Natural language reasoning in the output stream is a form of redundancy when the same reasoning can be expressed as executable code that also produces a concrete result.

In preliminary testing on Claude Sonnet 4.5 with the REPL-mandatory harness (file navigation tools stripped, forcing all codebase interaction through the REPL body), we observed approximately 60% reduction in output tokens compared to the same model with standard tool exposure. These numbers are from internal development testing, not controlled benchmarks. The effect appears model-conditional — models with strong tool-use training (Claude, GPT) benefit most; models with weaker tool-use capabilities (Qwen 3.6 in testing) did not show the same improvement. Rigorous evaluation is in progress.

The Design Principle

The underlying position is that a language model operating on a codebase should not interact with it sequentially through text primitives. The codebase is a structured artifact — it has a dependency graph, community structure, naming conventions, architectural patterns. An agent with access to these structures as first-class queryable objects can reason comprehensively about the environment rather than navigating it one file at a time.

The REPL body is the mechanism that exposes this structure. The model does not receive a bigger context window. It receives an environment it can traverse.

The inspiration draws from Recursive Language Models (Zhang, Krassa & Khattab, 2026) — the position that context is an environment to be navigated, not input to be stuffed into a window. RLM applies this to single-session reasoning. The REPL body applies it to the coding agent's relationship with its codebase.

Native Ori Memory

Ori CLI integrates with Ori Mnemos at the harness level. The Ori MCP server runs as a subprocess, spawned at session start from the bundled dependency. The agent accesses the full Ori retrieval stack through the REPL body and through dedicated tool interfaces.

REPL Memory Operations

Tool Memory Operations

What Persists

• Identity (self/identity.md). Agent name, personality, methodology. Loaded at session start. Survives compaction. Present in every turn's system prompt.
• Goals (self/goals.md). Active project threads. Refreshed periodically via warm context, not loaded once at session start and left to go stale.
• Knowledge (notes/). Wiki-linked notes in a knowledge graph with ACT-R decay, spreading activation, four-signal retrieval, and learning Q-values. See the Ori Mnemos README for the full retrieval architecture and the Recursive Memory Harness paper for the theoretical framework.
• Operational state (ops/). Daily status, reminders, session logs. High-decay memory that clears itself.
• Project brain (.aries/memory/). Per-project local memory that stays with the repository. Patterns, decisions, and learnings specific to the codebase.

Warm Context

A ~2K token block is assembled at session start and refreshed every 10 turns: core identity, active goals, and the highest-warmth notes from the knowledge graph. This block is injected at the top of every system prompt and survives context compaction. It serves as the agent's minimum viable continuity — the persistent self that remains even when conversation history is compressed.

Echo/Fizzle Feedback

When the harness retrieves memory notes before a model turn (preflight), it subsequently scans the model's response for references to those notes.

• Echo: The model referenced the note. The note's title terms appear in the response. A warmth boost is sent to Ori, which feeds into the Q-value reranking system. The note becomes more retrievable in future sessions.
• Fizzle: The note was retrieved but not referenced. No signal is sent. Natural ACT-R decay handles demotion.

This implements a closed feedback loop between retrieval and utility. The asymmetry is deliberate — false-negative echoes (missing a reference) are acceptable; false-positive echoes would corrupt Q-values. Over sessions, the retrieval surface converges toward notes that are genuinely useful for the agent's work patterns.

Reflection

The harness implements a Smallville-inspired importance accumulator. Tool-using turns accumulate importance at 3 points per turn; plain conversation accumulates at 1. When the accumulator crosses a threshold (default 150), the harness triggers a reflection: the cheap model slot synthesizes recent activity into a single prose-as-title insight, which is written to the Ori vault. This creates durable knowledge from ephemeral session activity without manual capture.

Phase-Gated Tool Exposure

Standard agent implementations expose all available tools on every API call. Each tool definition includes a full JSON schema. At 16+ tools, this represents 3–6K tokens of schema overhead per turn, regardless of whether the model requires those tools for the current operation.

Ori CLI implements phase-gated exposure:

The harness starts in lean phase. If the model requests a tool not in the lean set, the harness widens to full automatically on that turn. No tool-not-found errors. No manual phase management. Memory operations (VaultAdd, ProjectSave) are always available regardless of phase — memory capture is never gated.

Token savings: at 16 tools × ~300 tokens/schema × 20 turns, a typical session incurs ~96K tokens of schema overhead. Lean phase reduces this to ~18K in sessions where the model stays in explore/edit patterns.

Multi-Model Router

The harness supports four model slots with independent provider configuration:

Supported Providers and Models

Model Shortnames

Local Model Configuration

local:
  baseUrl: http://localhost:8080/v1
  gpuLayers: 20
  contextSize: 32768
  models:
    devstral:
      path: /path/to/devstral-small.gguf
      contextWindow: 131072
    qwen-coder-7b:
      path: /path/to/qwen2.5-coder-7b-instruct.gguf
      contextWindow: 32768

Start llama-server with: llama-server -m <path>.gguf -c 32768 --n-gpu-layers 20 --port 8080

Context Management

Compaction

When estimated token usage crosses a configurable threshold (default: 70% of context window), the harness compresses conversation history in two phases:

1. Prune phase. Old tool result content is erased, preserving call skeletons so the model retains awareness of what tools were used. The most recent tool results (last ~40K tokens) are protected.
2. Summary phase. Remaining conversation is summarized. Durable insights are extracted and persisted to vault or project brain before compression. Warm context survives intact.

Prompt Caching

On Anthropic models, ambient signatures (codebase structure + vault state) are placed before a cache_control marker in the system prompt. The stable prefix is cached across turns via Anthropic's prompt caching, reducing per-turn input token cost for structural context that does not change between turns.

Ambient Signatures

Two compressed representations are included in every turn's system prompt at configurable density (lean, standard, deep, max):

• Codebase signature. Top files by PageRank, community structure, key symbols, dependency patterns. Generated by the Python body at session start and after edits.
• Vault signature. Active notes, project distribution, warmth landscape, fading notes. Generated by Ori at session start and refreshed periodically.

These provide the agent with architectural proprioception — a compressed awareness of both codebase and memory state — without requiring explicit retrieval queries.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Ori CLI Harness                      │
│                                                             │
│  ┌───────────┐   ┌────────────┐   ┌──────────────────────┐ │
│  │  Ink TUI  │   │   Model    │   │   Phase-Gated Tool   │ │
│  │  React    │   │   Router   │   │     Exposure         │ │
│  │  Terminal │   │  (4 slots) │   │   lean ──► full      │ │
│  └───────────┘   └────────────┘   └──────────────────────┘ │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                     Agent Loop                         │ │
│  │                                                        │ │
│  │  system prompt ──► model ──► tool dispatch ──► post    │ │
│  │                                                        │ │
│  │  Warm context refresh (every 10 turns)                 │ │
│  │  Echo/fizzle tracking (per turn)                       │ │
│  │  Importance accumulation ──► reflection (at threshold) │ │
│  │  Compaction (at context threshold)                     │ │
│  └────────────────────────────────────────────────────────┘ │
│                                                             │
│  ┌────────────────────┐   ┌────────────────────────────┐   │
│  │    REPL Body       │   │    Ori Vault (MCP)         │   │
│  │                    │   │                            │   │
│  │  Python subprocess │   │  Persistent memory         │   │
│  │  tree-sitter index │   │  Knowledge graph           │   │
│  │  rustworkx graph   │   │  Learning retrieval        │   │
│  │  PageRank / HITS   │   │  ACT-R decay               │   │
│  │  Louvain community │   │  Q-value reranking         │   │
│  │  Judgment tools    │   │  Warm context assembly     │   │
│  │  rlm_call / batch  │   │  Echo/fizzle feedback      │   │
│  └────────────────────┘   └────────────────────────────┘   │
│                                                             │
│  ┌────────────────────┐   ┌─────────────────────────────┐  │
│  │  Project Brain     │   │  Filesystem · Bash · Web    │  │
│  │  (.aries/memory/)  │   │  Search · Fetch · Subagents │  │
│  │  Per-repo local    │   │  EnterPlanMode/ExitPlanMode │  │
│  └────────────────────┘   └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Tool Registry

In REPL-mandatory mode, file navigation tools (Read, Grep, Glob, VaultSearch, VaultRead, VaultExplore, VaultWarmth, ProjectSearch) are stripped from the registry, forcing all codebase and memory navigation through the REPL body. This eliminates the meta-decision of which navigation tool to use and consolidates all exploration into composable Python.

Configuration

~/.aries/config.yaml — generated with sensible defaults on first run.

agent:
  name: Aries                    # Agent name (used in identity, prompts, TUI)

models:
  primary:
    provider: anthropic
    model: claude-sonnet-4-6
  reasoning:
    provider: anthropic
    model: claude-opus-4-6
  cheap:
    provider: google
    model: gemini-2.5-flash

vault:
  path: ~/brain                  # Ori vault location
  preflight: true                # Retrieve memory before each turn
  postflight: true               # Track echo/fizzle, accumulate importance

repl:
  enabled: true                  # Spawn Python body at session start
  timeoutMs: 30000               # Per-execution timeout
  maxRlmCalls: 15                # rlm_call cap per top-level exec
  sandbox: same_process          # same_process | docker | firecracker

compact:
  auto: true                     # Auto-compact at threshold
  threshold: 0.7                 # Fraction of context window

signature:
  codebase:
    level: standard              # lean | standard | deep | max
    maxTokens: 2000
  vault:
    level: standard
    maxTokens: 1500
  cachePrefix: true              # Anthropic prompt cache marker

permissions:
  mode: auto                     # auto | ask | manual
  allowBash: true
  allowWrite: true
  allowNetwork: true

Project Structure

ori-cli/
├── src/
│   ├── index.ts                 # Entry point — parchment terminal, session bootstrap
│   ├── loop.ts                  # Agent loop — turn management, phase tracking, compaction
│   ├── prompt.ts                # System prompt assembly — identity, rules, signatures
│   ├── config/                  # Configuration types and loading
│   ├── router/                  # Multi-model router and provider implementations
│   │   └── providers/           # Anthropic, Google, OpenAI-compatible, Groq, etc.
│   ├── tools/                   # Tool definitions and execution engine
│   ├── memory/                  # Vault integration, warm context, echo/fizzle, reflection
│   ├── repl/                    # REPL bridge — JSON-RPC protocol, restart-on-crash
│   ├── session/                 # Session storage and replay
│   ├── onboarding/              # First-run detection and setup
│   ├── ui/                      # Ink/React TUI — messages, markdown, status bar, input
│   └── utils/                   # Token estimation, message helpers
├── body/
│   ├── server.py                # Python REPL server (JSON-RPC over stdin/stdout)
│   ├── codebase.py              # CodebaseGraph — rustworkx graph with PageRank/HITS/Louvain
│   ├── indexer.py               # tree-sitter parser and symbol extraction
│   ├── judgment.py              # AST-shape matching, duplication detection, convention finding
│   ├── vault.py                 # Vault MCP client — memory operations from Python
│   ├── rlm.py                   # rlm_call — recursive sub-LLM invocation
│   ├── repl.py                  # REPL execution engine with security constraints
│   └── security.py              # Import whitelist, syscall restrictions
└── package.json

Status

Beta. Phases 0–8 of the build plan are implemented and operational:

Remaining: Phase 9 (warmth signals in agent loop), Phase 10 (warm context expansion), Phase 12 (benchmark paper). Coming soon.

License

Apache-2.0

Memory is sovereignty.