Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (47 loc) · 5.23 KB

AGENTS.md

File metadata and controls

66 lines (47 loc) · 5.23 KB
Raw

Agent Operating Instructions

This file is the shared briefing for any coding agent working in this repository — Codex, Claude Code, OpenCode, Aider, Cursor, or anything else that reads AGENTS.md / CLAUDE.md at repo root.

What this project is

Sacred Brain — a small personal memory+agents stack running on a Raspberry Pi. It is starting a compatibility rename toward the neutral name agent-memory; keep Sacred Brain names working while adding agent-memory aliases.

Two core services run under systemd:

  • Hippocampus (:54321) — FastAPI memory store, Mem0-backed with SQLite persistence. The authoritative store.
  • Memory Governor (:54323) — FastAPI policy/coordination layer in front of Hippocampus. Handles salience, consolidation, tiers (safe/raw), scopes, and durable write queueing.

See docs/README.md for the full docs index. docs/ARCHITECTURE.md + docs/STACK.md are the quickest on-ramp for the live picture; CHANGELOG.md is the timeline.

Where work lives

  • Design docs → docs/*.md. Permanent. Explain what and why.
  • Task files → agents/tasks/NNN_slug.md. Disposable work orders — one focused PR each. Format in agents/tasks/README.md.
  • Historical tasks (Codex-only) → codex/tasks/001–009. Kept for provenance; do not add new files here. New tasks go under agents/tasks/.
  • Session notes → SESSION_LOG.md and CHANGELOG.md.

Expected workflow

  1. Read the design docs relevant to the area you're touching (usually docs/MEMORY_GOVERNOR.md, docs/ARCHITECTURE.md).
  2. Check agents/tasks/ for a pending task. If none fits, author one using the template in agents/tasks/README.md before coding.
  3. Implement in small, reviewable steps. Keep tests passing (justfile has smoke, health, config-check).
  4. Update the task file status inline ((in progress) → (done)).
  5. Note significant milestones in SESSION_LOG.md or CHANGELOG.md.

Ground rules

  • /home/ryer/projects/sacred-brain/ is a back-compat symlink to /home/ryer/projects/agent-memory/ — same tree, either path is fine to edit.
  • Hippocampus stays a dumb semantic store. New policy/lifecycle logic goes in the Governor.
  • There are two deployment layouts, and they are not interchangeable:
    • User layout — this is the live one (red5). Runs as ryer via systemctl --user; state in ~/.local/state/agent-memory/, config in ~/.config/agent-memory/, units in ops/systemd/user/.
    • System layout. Runs as the agent-memory user (nologin); state in /var/lib/agent-memory/, config in /etc/agent-memory/, docs in /usr/local/share/agent-memory/docs/, installed by the Makefile. There is no source tree on a deployed host: every unit invokes a console script from the pipx venv, so a checkout is build-time only. No host currently runs this layout (red4 was decommissioned 2026-08-28).
  • All new memory features should respect the safe/raw tier split and scope filtering — don't bypass them.

Per-agent quirks

If an agent needs extra guidance beyond what's here, add a short section below with the agent's name. Everything above applies to all agents.

If .agents/CONTEXT_MEMORY.md or .claude/CONTEXT_MEMORY.md exists in the workspace, treat its bullet list as recalled long-term memory for this session. It is generated by scripts/governor_context.sh and is safe to ignore if absent.

To search long-term memory on demand (including ChatGPT conversation imports), run agent-memory-search <query> [user_id] [limit] (legacy alias: sacred-search). Defaults: user_id=sam, limit=5. Use user_id=david to search memories extracted from David's ChatGPT history. This hits Hippocampus directly — archive memories that the Governor's /recall suppresses are included here.

Codex

Legacy task files under codex/tasks/ are historical; codex/instructions.md is superseded by this file for new work. The Governor bridge (see docs/CODEX_BRIDGE.md) pre-pulls recalled memories into .agents/CONTEXT_MEMORY.md via the codex-with-governor launcher wrapper — the same file OpenCode reads.

Claude Code

Project-scoped memory in .claude/ is welcome. The Governor bridge (see docs/CLAUDE_CODE_BRIDGE.md) writes recalled memories into .claude/CONTEXT_MEMORY.md on SessionStart and ships transcript tails to /observe before compaction.

OpenCode

Reads this file directly. The Governor bridge (see docs/OPENCODE_BRIDGE.md) writes recalled memories into .agents/CONTEXT_MEMORY.md via either a native pre-session hook or the opencode-with-governor launcher wrapper.

Pi (pi-coding-agent)

Pi exposes a typed extension API instead of a shell-hook config slot, so the bridge ships as a TypeScript extension at ~/.pi/agent/extensions/sacred-brain-bridge.ts (sourced from extensions/pi-bridge.ts in this repo). It subscribes to session_start/before_agent_start/session_before_compact/session_shutdown and (a) pulls recalled memory into .agents/CONTEXT_MEMORY.md and directly into the system prompt, (b) POSTs the to-be-summarised tail to /observe with source pi:precompact (capped at 0.35 salience), and (c) drains ~/.cache/agent-memory/pi-pending-outcome.jsonl on session shutdown. See docs/PI_BRIDGE.md.