Adding memory to Orca

Orca's session journal in agent-session-journal.db and full recall across hosted agents

Orca persists its unified session journal in agent-session-journal.db under its userData directory (~/Library/Application Support/orca on macOS, ~/.config/orca on Linux, %APPDATA%/orca on Windows). Each session has metadata in agent_session_records and structured render items in journal_rows.

Option A: Orca v2 plugin (extensions/orca)

In Orca (>=1.4.248), open Orca → Plugins → extensions/orca. The orca-plugin.json v2 trusted-worker plugin adds:

  • agent.prompt.before: injects relevant <deja-recall> context for the active workspace within Orca's 2s hook budget.
  • agent.tool.before: appends recall context when spawning Agent or Task subagents without mutating Bash, Read, or Edit calls.
  • agent.tool.after: observe-only in Orca's host API (Orca ignores return payloads here, so failed-command fixes require native hooks below).
  • Commands deja.orient (workspace orientation via deja hook-context --plain) and deja.recall (deja search / deja last).

If settings.json already carries a native UserPromptSubmit hook from deja install orca-auto, the plugin stands down automatically so recall is never injected twice.

Option B: Native CLI wiring (MCP + hooks)

deja install orca

That writes three things under Orca's data directory (reversible with deja uninstall orca):

  • The MCP server, into mcp.json under mcpServers.deja.
  • The deja-history skill, at skills/deja-history/SKILL.md.
  • The /deja command, at commands/deja.md.
deja install orca-auto

Everything above, plus six lifecycle hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse for failed-command fixes, PreCompact, SessionEnd) and statusLine in settings.json.

The part that is not about this harness

The local BM25 index (~/.cache/deja/index.db) covers every agent's transcripts on the machine — forty-seven of them today, each in its own format — so work recorded in Orca's journal is searchable from Claude Code, Codex, Cursor or opencode, and the reverse. Indexing and search stay local, and credentials are stripped as the index is built.

Getting started · Switching between agents · The Orca session format

Found this useful? Star deja-vu on GitHub.