Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.orinadus.com/llms.txt

Use this file to discover all available pages before exploring further.

Claude, Copilot, Gemini, Codex, OpenCode, the shell, git — each tool keeps its own history and none of them share it. Urchin runs locally, collects events from every tool into a single append-only journal, and exposes that journal over MCP and HTTP so any agent, IDE, or script can read what every other tool did. Urchin does not own your tools. It connects them.

​
What it does

  • Collects — passive pull collectors for shell history, git commits, Claude, Copilot, Gemini, Codex, OpenCode, and local models. Read-only. No write-back to source tools.
  • Stores — events land in an append-only JSONL journal at ~/.local/share/urchin/journal/events.jsonl. Events are never mutated.
  • Exposes — an MCP server (stdio, JSON-RPC 2.0) for IDE integrations, and an HTTP intake server for SDK and script ingestion.

​
What it does not do

  • It does not replace or wrap your tools.
  • It does not modify your shell config, git hooks, or IDE settings automatically.
  • It does not send data anywhere by default. Cloud sync requires an explicit cloud_token.

​
Architecture overview

Collectors (read-only)      Journal (append-only JSONL)      Consumers
────────────────────        ──────────────────────────        ──────────────────────
shell / git / claude   →    ~/.local/share/urchin/           MCP (stdio)
copilot / gemini       →    journal/events.jsonl       →    HTTP GET
codex / opencode       →                                     vault projection
HTTP POST /ingest      →                                     cloud sync

​
Crate structure

CrateRole
urchin-corePure types: Event, Journal, Config, Identity. Zero I/O except journal reads/writes.
urchin-intakeAxum HTTP daemon. POST /ingest, GET /health. Binds 127.0.0.1:18799.
urchin-mcpMCP stdio server. 10 tools over JSON-RPC 2.0.
urchin-collectorsShell, git, Claude, Copilot, Gemini, Codex, OpenCode, local-model collectors.
urchin-vaultProjects events into ~/brain daily notes inside marker-guarded blocks.
urchin-agentReAct reflection loop: load context → synthesise → write Agent event back.
urchin-sdkHTTP client for urchin-intake and Orinadus cloud hub.
urchin-cliSingle binary urchin. All subcommands.

​
Event model

Every unit of memory is an Event:
FieldTypeRequiredNotes
idUUID v4 stringYesGenerate client-side. Deduplication key.
timestampISO 8601 UTCYesRFC 3339 format.
sourcestringYesclaude, copilot, shell, git, mcp, cli, etc.
kindenum stringYesconversation / agent / command / commit / file / decision
contentstringYesThe memory payload. Must not be blank.
workspacestringNoAbsolute path to repo or workspace.
sessionstringNoSession identifier.
titlestringNoShort display title.
tagsstring[]NoFree-form tags. Omitted from JSONL when empty.
actorActor objectNo{ account, device, workspace } — all optional.
brainstringNoVault identifier for multi-brain setups.
None/empty optional fields are omitted from the JSONL output. No null values are written to disk.