Architecture guide - technical + UX - updated 2026-05-26
This tutorial explains the project from first principles. You do not need to know the codebase first. Read it like a guided tour: what problem Eagle Mem solves, how hooks move data through the system, how SQLite stores shared memory, and why the user experience is intentionally quiet until the agent needs help.
02 / Basics
Eagle Mem exists because coding agents are powerful but forgetful. A normal agent session has short-lived context. Eagle Mem adds a local layer around that session so important history, decisions, tasks, and feature risks survive between turns, compactions, and even different agents.
Recall means the next agent can see useful project history without rereading everything. Eagle Mem stores session summaries, project overviews, agent memories, task state, and indexed source chunks in one local SQLite database.
Guardrails mean the agent gets warned before it repeats known mistakes, reverts decisions, edits sensitive files, or tries to release code before impacted features have been verified.
Lanes let broad work split across agents. A coordinator can create durable worker lanes with owners, worktrees, validation commands, status notes, and handoffs that survive compaction.
Eagle Mem is not a hosted memory service. It is not a vector database. It is a local runtime made of hook scripts, CLI commands, and a SQLite database. Agents keep working in their normal terminal UI, while Eagle Mem quietly injects context, records what happened, and blocks risky release boundaries when verification is still pending.
eagle-mem compaction reads project-level state from SQLite: enriched summaries, durable tasks, stale tasks, active orchestration lanes, and recent durable updates. Claude Code, Codex, and Google Antigravity have hook-backed automatic recovery around compact and clear events. Grok can use the same state through linked skills and CLI commands.
| Term | Plain-English Meaning | Where It Lives |
|---|---|---|
Session |
One agent conversation or run in a project. | sessions table |
Hook |
A script the agent calls at a specific lifecycle moment, such as startup or before a tool call. | hooks/*.sh |
Observation |
A lightweight record of one tool action: read, edit, shell command, output size, and touched files. | observations table |
Summary |
The durable lesson from a session: request, completed work, learned context, decisions, gotchas, and files. | summaries and summaries_fts |
Feature |
A user-facing or system behavior mapped to files, dependencies, and smoke tests. | features, feature_files, feature_smoke_tests |
Lane |
An isolated workstream assigned to an agent, usually in a git worktree. | orchestrations, orchestration_lanes |
03 / System Map
Think of Eagle Mem as five layers. The user interacts with an agent. The agent fires hooks. The hooks call shared library functions. The library reads and writes SQLite. CLI commands and skills expose the same state to humans and agents.
Eagle Mem does not make every agent learn a new API. Instead, each agent gets a thin adapter that registers its native hook format and points those hooks at the same installed scripts under ~/.eagle-mem. Once a hook script starts, it normalizes the agent source and uses the same library and database functions as every other agent.
04 / Install Runtime
Installation converts the source package into a local runtime. The source repo stays the product code. The installed runtime under ~/.eagle-mem is what the agents actually execute from hooks.
The user runs npm install -g eagle-mem, then eagle-mem install. The bin entry dispatches to scripts such as install.sh, search.sh, feature.sh, and orchestrate.sh.
The installer checks for an FTS5-capable sqlite3, jq, optional rtk, and at least one supported agent environment. FTS5 matters because summaries, code chunks, and mirrored artifacts are searched with SQLite full-text search.
The hook scripts, shared libraries, migrations, and CLI support scripts are copied into ~/.eagle-mem. This makes the runtime independent of the current checkout location.
db/migrate.sh creates or updates ~/.eagle-mem/memory.db. Runtime connections enable WAL mode, foreign keys, and a busy timeout so hook writes can coexist during active agent sessions.
Claude Code hooks are patched into ~/.claude/settings.json. Codex hooks are registered in ~/.codex/hooks.json. Google Antigravity SDK hooks are registered programmatically in google_antigravity_hook.py using native Python async hooks. Grok has skills and CLI access.
Eagle Mem skills are symlinked into each agent's skill directory. Claude receives CLAUDE.md instructions. Codex receives AGENTS.md instructions. Google Antigravity SDK maps and mirrors standard brain planning artifacts (plans, tasks, walkthroughs). Grok receives skills under ~/.grok/skills.
| Path | Role | Why It Exists |
|---|---|---|
bin/eagle-mem |
Command dispatcher | Maps CLI subcommands to scripts under scripts/. |
~/.eagle-mem/hooks/ |
Installed hook entrypoints | Stable scripts that agent configs can call. |
~/.eagle-mem/lib/ |
Shared runtime functions | Keeps project detection, agent detection, database access, guardrails, and redaction in one place. |
~/.eagle-mem/db/ |
Migrations and schema | Creates the local SQLite/FTS5 database. |
~/.eagle-mem/scripts/ |
CLI command implementations | Lets users and agents search, verify, curate, orchestrate, and inspect status. |
~/.eagle-mem/memory.db |
Single source of local memory | Stores shared state across Claude Code, Codex, Grok skills, Google Antigravity hooks, compactions, and sessions. |
05 / Hook Lifecycle
The hook lifecycle is the heart of Eagle Mem. The agent does not need to remember to run anything. It naturally starts, receives user prompts, uses tools, and ends turns. Eagle Mem attaches useful behavior to those moments.
Upserts the session, auto-provisions scan/index/prune/curate jobs, checks updates, and injects a compact banner, overview, recent recall, stored memories, tasks, and code hints.
Tracks turn count for context pressure, searches summaries and indexed code through FTS5, and injects relevant recall. Broad-work prompts can also trigger the orchestration protocol reminder.
Runs before shell commands and mutations. It can block release-boundary commands with pending feature verification, rewrite raw shell output through RTK, and surface guardrails before edits.
Stores observations, mirrors agent memories/plans/tasks, records pending feature verification after edits, surfaces stale-memory warnings, and reminds the agent about file-specific decisions or feature dependencies.
Runs at turn end. It reconciles current diffs into pending feature verification, extracts explicit summary fields when available, falls back to heuristic summaries, and queues LLM enrichment in the background.
Re-syncs task files, marks the session completed, and prunes older observations for the project.
A memory system that only saves at the end helps future sessions, but it cannot prevent the current agent from making a bad move. Eagle Mem splits behavior by timing: recall at start, search on prompt, guard before action, record after action, summarize at stop, and clean up at session end.
06 / Technical Architecture
The project is agent-generic below the adapter layer. Claude Code, Codex, and Google Antigravity have direct lifecycle hook adapters, while Grok participates through skills and CLI commands. Eagle Mem normalizes each supported surface into the same project memory model.
Registered through ~/.claude/settings.json. Uses Claude hook events such as SessionStart, PreToolUse, PostToolUse, Stop, SessionEnd, TaskCreated, and TaskCompleted.
Registered through ~/.codex/hooks.json after enabling codex_hooks. Shell protection covers current Codex shell tool paths, including exec_command, shell_command, and unified_exec.
Installed through ~/.grok/skills and the eagle-mem grok-bootstrap command. Grok can search memory, inspect tasks, coordinate lanes, and check compaction readiness through the same SQLite-backed CLI. Native lifecycle hooks are not assumed yet.
Integrated programmatically via integrations/google_antigravity_hook.py. Connects Antigravity's async Python hook triggers directly to Eagle Mem's lifecycle events, enabling direct database writes and background curation/sync.
| Problem | Normalization | Result |
|---|---|---|
| Each agent names tools differently. | eagle_is_shell_tool treats known shell tool names as the same category. |
Release boundaries and RTK token guard work across agents. |
| Each agent identifies sessions differently. | Hooks parse session_id, cwd, transcript path, workspace paths, and agent-specific markers. |
Rows attach to the correct project and session. |
| Agent output must look different. | eagle_emit_context_for_agent can keep Codex compact and user-clean while Claude receives richer hook context. |
The same memory is useful without flooding the UI. |
| Future agents may only support some hook moments. | The system treats each hook as additive. Missing hooks reduce features but do not invalidate the core database model. | New adapters can start small and grow toward full support. |
Any future agent can become an Eagle Mem participant if it can run local scripts at lifecycle moments, pass JSON or structured context through stdin, accept context or block decisions from stdout, and preserve a project working directory. Full support needs five moments: start, prompt, before tool, after tool, and stop.
07 / Technical Architecture
The database is the shared memory. It is intentionally boring: one local SQLite file, WAL mode, FTS5 search tables, and small normalized records. This keeps the system portable and avoids a background service.
| Table Family | Question It Answers | Used By |
|---|---|---|
sessions, summaries, summaries_fts |
What happened before? What did the agent learn? What should the next agent remember? | SessionStart, UserPromptSubmit, search CLI, Stop |
observations |
What files and commands were actually used during sessions? | PostToolUse, curator, search session drill-down |
overviews |
What is this project, in a concise briefing? | SessionStart, overview CLI, scan |
code_chunks, code_chunks_fts |
Which source files look relevant to this prompt? | UserPromptSubmit, index CLI |
graph_nodes, graph_edges, graph_nodes_fts |
Which files, declarations, sessions, memories, and relationships make up the codebase graph? | graph CLI, scan, index, overview set, curator Dream Cycle |
agent_memories, agent_plans, agent_tasks |
What durable agent artifacts should be shared across Claude Code, Codex, Grok, and Antigravity? | PostToolUse, SessionEnd, skills, search CLI |
features, feature_files, feature_dependencies, feature_smoke_tests |
Which user-facing behavior is connected to a file or dependency? | PostToolUse, PreToolUse, feature CLI |
pending_feature_verifications |
Which affected features still need smoke testing before release? | PreToolUse release blocks, Stop reconciliation, feature verify/waive |
orchestrations, orchestration_lanes, worker tables |
Who owns each lane, what is blocked, and what validation is required? | orchestrate CLI, SessionStart task injection, worker handoffs |
eagle-mem graph rebuild is the supported recovery command when graph search shows stale deleted files or stale declarations. It filters missing tracked paths, clears code graph nodes and chunks for the current project, preserves the canonical overview, rewires file nodes, and runs eagle-mem index --force so declarations are file-scoped instead of colliding by bare function name.
08 / Technical Architecture
Recall is the "start warm" feature. It gives the agent the right memory at the right time without dumping months of history into every prompt.
The hook normalizes the current project from workspace paths, transcripts, remembered session markers, or the current working directory. This prevents worktrees and resumed sessions from becoming separate memories by accident.
SessionStart creates the visible "Recall Ready" banner, then adds overview, recent summaries, stored memories, tasks, code index stats, and hot files when available.
UserPromptSubmit ignores tiny prompts with fewer than three words. For real prompts, it extracts useful search terms, searches summaries and code chunks, and returns compact relevant recall.
Stop persists summary data immediately using explicit fields or heuristics, then enrichment can improve the record later without delaying the user's session.
Recall helps the agent know what happened before. Enforcement stops risky actions. A strong architecture needs both. Eagle Mem uses FTS5 recall for context and feature verification for release safety.
09 / Technical Architecture
Guardrails are timed around risk. Reading a file is low risk, so Eagle Mem surfaces decisions and feature context after reads. Editing and release commands are high risk, so Eagle Mem checks before or immediately after those actions.
| Guardrail | Trigger | User Experience |
|---|---|---|
| Decision recall | Reading a file with past decisions | The agent sees a note like "Do not revert without explicit user request." |
| Stale memory check | Editing a file that may contradict stored memory | The agent is told to update memory if the edit makes old context wrong. |
| Feature guardrail | Reading or editing a file mapped to a feature | The agent sees dependencies, related files, last verification, and smoke tests. |
| Release boundary block | git push, gh pr create, or package publish with pending verification |
The command is denied with exact verification or waiver instructions. |
| Token guard | Shell commands likely to dump large raw output | The command is rewritten through RTK or blocked with a compact alternative. |
10 / Technical Architecture
Lanes are the architecture for work that is too wide for one agent turn. Instead of one agent keeping a fragile mental checklist, Eagle Mem stores lane ownership and status in SQLite so another agent can continue after compaction or handoff.
The active agent defines the goal, splits independent lanes, avoids duplicate work, integrates results, and runs final validation.
A worker owns one bounded lane. It usually runs in a git worktree and should not rewrite another worker's files or revert unrelated edits.
Lane records include owner, target agent, status, worktree path, validation command, notes, and handoff output.
Eagle Mem can route broad work to different agents by default. For example, a Codex or Antigravity coordinator can spawn Claude Code or Grok workers; any agent can coordinate or execute worker lanes. The goal is not to make agents compete, but to let each lane have one owner and one validation path.
# Agent-run protocol, not usually a user task
eagle-mem orchestrate init "Ship the release safely"
eagle-mem orchestrate lane add api --agent codex --desc "Routes and tests" --validate "npm test"
eagle-mem orchestrate spawn api
eagle-mem orchestrate sync
eagle-mem orchestrate handoff --write docs/handoff-context.mdContext windows end. Tools fail. A user may switch from Claude Code to Codex, Grok, or Antigravity. A worker may finish while the coordinator is compacted. Lanes make this survivable because the state is outside any one transcript.
11 / UX Architecture
Eagle Mem's UX is not a large screen. It is a set of small, timely interventions inside the agent's existing workflow. The best UX here is often invisible: the user notices that the agent remembers, avoids mistakes, and coordinates work, but does not need to babysit a new interface.
Users already live in Claude Code, Codex, Grok, or Antigravity. Eagle Mem should not require them to open a dashboard before every task. Hooks/skills inject context where the agent already is.
SessionStart gives a compact status. Prompt recall appears only for meaningful prompts. Release blocks happen only when current changed files map to pending feature verification.
Most messages are addressed to the agent because the agent is the actor about to read, edit, push, or spawn work. The user benefits from better behavior without extra manual steps.
The database is local. Logs and memory are local. There is no hosted memory service. This is important for repo privacy and for agent adoption across many project types.
When a release command is blocked, the message must say exactly why, which features are pending, what smoke tests to run, and how to verify or waive.
Claude and Antigravity can handle richer hook context. Codex and Grok should keep user-facing replies clean and let Turn Stop/Stop capture summaries from normal prose.
12 / UX Architecture
Eagle Mem has many small surfaces. Each one has a specific UX job. Together, they make memory feel automatic instead of heavy.
Job: Build confidence. It checks prerequisites, shows what was installed, and explains when manual statusline patching is needed.
Failure to avoid: Silent partial setup where hooks are not actually active.
Job: Confirm memory is active at session start and show useful counts: sessions, sources, memories, tasks, code chunks, and last work.
Failure to avoid: Long startup dumps that cost tokens and bury the user's prompt.
Job: Give the agent enough past context to act correctly. It should be short, attributed, and directly relevant to the current prompt.
Failure to avoid: Treating memory search output as the final answer.
Job: Point the agent to likely source files without pretending those snippets replace reading the actual code.
Failure to avoid: Making stale code index hits sound authoritative when current code has not been opened.
Job: Stop release commands when affected features still need verification. The message is a safety gate, not a suggestion.
Failure to avoid: Blocking without telling the user how to unblock safely.
Job: Prevent huge raw shell output from consuming context. It suggests an RTK equivalent and allows a short-lived escape hatch.
Failure to avoid: Making routine exploration feel broken. The replacement command must be clear.
Job: Keep Eagle Mem visible in a tiny terminal footprint: version, session count, memory count, and turn count.
Failure to avoid: Turning the terminal into a dashboard that competes with coding.
Job: Teach agents when to search memory, manage tasks, build overviews, or coordinate lanes. Skills are UX for the agent's behavior.
Failure to avoid: Asking the user to run internal orchestration steps that the agent should run.
13 / Tutorial
This walkthrough explains how the system feels to a beginner. The same flow works whether the active agent is Claude Code, Codex, Grok, or Antigravity.
The user installs Eagle Mem. The installer sets up hooks, migrations, skills, config, and optional statusline integration. After that, the user opens their normal agent in a project.
npm install -g eagle-mem
eagle-mem installSessionStart runs automatically. On a new project, background scan and index jobs can create a project overview and searchable source chunks. On an existing project, the agent sees compact recall.
The user asks, "Can you fix the release guardrail bug?" UserPromptSubmit turns that into an FTS5 query, finds relevant prior summaries and code chunks, and injects only the useful context.
PostToolUse records observations. If a file belongs to a tracked feature, Eagle Mem can create pending verification records tied to the feature, file, and current diff fingerprint.
If the agent runs git push, gh pr create, or package publish while affected features are pending, PreToolUse blocks the command and tells the agent what must be verified.
After smoke tests pass, the agent runs eagle-mem feature verify <name> --notes "what passed". If the exception is intentional, it can waive a specific pending record with a reason.
Stop saves what happened so the next session can recall it. Codex and Grok can keep the final reply clean; Claude and Antigravity can use richer summary fields/artifacts when appropriate. Either way, the durable memory lands in SQLite.
14 / All-Agent Applicability
The project natively supports Claude Code, Codex, and Google Antigravity with lifecycle hooks, and Grok with skills plus CLI workflows. The architecture should scale to any coding agent that can run local hooks, wrapper scripts, or a skill-like command surface. The integration work should live at the edge, not inside the database model.
| Capability | Needed For | Fallback If Missing |
|---|---|---|
| Session start hook | Inject overview, summaries, memories, tasks, and code hints. | User can run eagle-mem search manually, but warm start is weaker. |
| User prompt hook | Search memory in response to the current request. | Agent can use the search skill manually. |
| Pre-tool hook | Block releases, enforce guardrails, and rewrite noisy commands before context damage. | Post-action warnings still work, but safety is weaker. |
| Post-tool hook | Record observations, mirror tasks, and create pending feature verification records. | Stop summaries can still save high-level memory, but tool history is thin. |
| Stop hook | Persist session summaries and learned decisions automatically. | Manual eagle-mem session save can capture summaries. |
~/.eagle-mem/hooks/.EAGLE_AGENT_SOURCE to a stable value, such as codex, claude-code, grok, antigravity, or a future agent key.session_id, cwd, tool name, tool input, and optional transcript path.Do not fork the memory model for every agent. Add a thin adapter, normalize into the same hook contract, and keep shared behavior in lib/ and db/. Agent-specific behavior should explain how to speak to the agent, not redefine what memory means.
15 / Source Map
Use this map when you want to verify the tutorial against the implementation. Start with the row that matches your question.
README.md - product layers, getting started, hook table, token savings, anti-regression, lanes.package.json - version, package entrypoint, published file set, project keywords.bin/eagle-mem - subcommand dispatcher.scripts/help.sh - user-facing command map.scripts/search.sh, scripts/feature.sh, scripts/orchestrate.sh - main user and agent command surfaces.scripts/install.sh - runtime copy, migrations, hook registration, skills, statusline, config.lib/codex-hooks.sh - Codex hook enablement and hook registration.lib/hooks.sh - Claude Code hook patching.hooks/session-start.sh and lib/hooks-sessionstart.sh - warm start, auto-scan, auto-index, auto-prune, auto-curate.hooks/user-prompt-submit.sh - context pressure, prompt search, relevant recall and code hits.hooks/pre-tool-use.sh - release blocking and token guard.hooks/post-tool-use.sh and lib/hooks-posttool.sh - observations, mirrored artifacts, feature impacts, stale hints.hooks/stop.sh and hooks/session-end.sh - summary persistence and cleanup.lib/common.sh - project detection, agent detection, command parsing, redaction, release command detection.lib/db-core.sh and lib/db.sh - SQLite connection setup and module loading.lib/db-graph.sh - graph node/edge helpers, code graph rebuild, file path normalization, and Dream Cycle batching.lib/db-features.sh - feature lookup, pending verification, verify/waive behavior.db/*.sql - schema and migrations for all persistent state.skills/eagle-mem-search/SKILL.md - when and how agents should search memory.skills/eagle-mem-orchestrate/SKILL.md - coordinator and worker lane rules.skills/eagle-mem-tasks/SKILL.md - task loop behavior for long sequential work.README.md for the product promise.scripts/install.sh to understand activation.lib/common.sh and lib/db-features.sh for cross-agent normalization and safety gates.db/ to understand persistent state.