AI Agents
Persistent, searchable memory for coding agents. Query context on demand instead of cramming everything into project files.
Why recuerd0
MEMORY.md works — until it doesn't. 200 lines, project-scoped, no search, no versioning, no cross-project queries. Every session starts with the same truncated cheat sheet.
recuerd0 is a CLI and REST API — the deep, searchable, cross-project knowledge layer your agent queries on demand. It pulls exactly the context it needs — architecture decisions, debugging patterns, API conventions — without bloating the system prompt. Keep MEMORY.md for quick hits. Use recuerd0 for everything else.
The Three Layers
Each layer serves a different scope and lifespan.
| Layer | Role | Scope | Lifespan |
|---|---|---|---|
MEMORY.md |
Quick cheat sheet — linting rules, project conventions, gotchas | Single project | Overwritten often |
recuerd0 |
Deep knowledge — architecture, patterns, decisions, debugging guides | Cross-project | Versioned, persistent |
Transcripts |
Session logs — raw conversation history for later mining | Single session | Archive, rarely queried |
Project Setup
Create a workspace and configure your project in two steps.
1. Create a workspace
recuerd0 workspace create --name "my-rails-app" --description "Rails 8 monolith"2. Add project-local config
account: personal
workspace: 1.recuerd0.yaml in your project root, you can omit --workspace from all commands when working in that directory.
CLAUDE.md hint
Add a one-liner to your CLAUDE.md so the agent knows recuerd0 is available.
## Project Knowledge
Deep project knowledge (architecture, patterns, decisions) is stored in recuerd0.
Search with: recuerd0 search "<query>"
Read with: recuerd0 memory show --workspace 1 <id>Workflows
Common patterns for using recuerd0 with AI coding agents.
Pre-session context loading
Search for relevant context before starting a task. The agent can do this automatically if your CLAUDE.md tells it to.
# Find architecture decisions relevant to the task
recuerd0 search "authentication AND rails"
# Load a specific memory
recuerd0 memory show --workspace 1 12
# Discover related memories in other workspaces
recuerd0 memory link list 12 --workspace 1Capture knowledge during a session
When you solve something worth remembering, save it immediately.
recuerd0 memory create --workspace 1 \
--title "FTS5 error handling in Rails" \
--category discovery \
--tags "sqlite,fts5,errors,rails" \
--content "# FTS5 Error Handling
SQLite FTS5 syntax errors surface as ActiveRecord::StatementInvalid,
NOT as SQLite3::SQLException directly.
Rescue ActiveRecord::StatementInvalid and check
e.message.include?(\"fts5\") to distinguish from other SQL errors."Archive transcripts
Pipe session transcripts into recuerd0 for later mining.
cat transcript-2026-02-05.md | recuerd0 memory create \
--workspace 2 \
--title "Session: Auth refactor" \
--tags "transcript,auth,2026-02" \
--content -Track evolving decisions
Use versions to record how decisions change over time. The original stays intact; each update creates a new version.
# Initial decision
recuerd0 memory create --workspace 1 \
--title "Auth strategy" \
--category decision \
--tags "auth" \
--content "# Auth Strategy\n\nUsing session-based auth with Rails 8 generator..."
# Months later — decision evolved
recuerd0 version create --workspace 1 42 \
--category decision \
--content "# Auth Strategy v2\n\nAdded Bearer token API auth alongside sessions..."Integrations
Connect recuerd0 to Claude Code, Cursor, ChatGPT, and anything that speaks HTTP or shell.
Claude Code Plugin
Native integration for Claude Code. Save sessions, search, and manage workspaces without leaving the agent.
/plugin marketplace add maquina-app/rails-claude-code
/plugin install recuerd0@maquinaThe plugin provides slash commands for saving session knowledge, searching memories, and workspace management — all within the Claude Code conversation flow.
Auto-Save Hooks
The plugin registers two Claude Code lifecycle hooks that capture session state automatically. No manual commands, no forgetting to save.
| Hook | When it fires | What it does |
|---|---|---|
Stop |
After each assistant turn, at most once every 15 minutes | Checkpoint memory tagged claude-code,auto-save,stop |
PreCompact |
Right before Claude Code compresses the conversation | Emergency snapshot tagged claude-code,auto-save,precompact |
Both hooks capture the last 200 lines of the session transcript, build a titled Markdown memory, and save it to the configured workspace via the recuerd0 CLI. The title includes an ISO timestamp and session ID. The source is always claude-code-session, so you can filter auto-saved memories out of manual queries.
Workspace routing
Drop a .recuerd0.yaml at each project root and every session started in that directory lands in the right workspace.
workspace: "12"recuerd0 CLI is missing, no account is configured, or no workspace is resolvable. A fresh install with no config produces zero activity — nothing is ever captured without your setup.
Tuning
| Env var | Default | Purpose |
|---|---|---|
RECUERD0_HOOK_DISABLE | unset | Set to 1 to disable both hooks entirely |
RECUERD0_STOP_INTERVAL_MINUTES | 15 | Minimum minutes between Stop saves |
RECUERD0_HOOK_TAIL_LINES | 200 | Transcript lines captured per save |
Turning it off
Four ways to stop auto-saving, from least invasive to most.
| Scope | How |
|---|---|
| Current shell | export RECUERD0_HOOK_DISABLE=1 before launching Claude Code |
| Single project | Remove the project's .recuerd0.yaml and don't set RECUERD0_WORKSPACE |
| Just one hook | Edit ${CLAUDE_PLUGIN_ROOT}/hooks/hooks.json and delete the Stop or PreCompact block |
| Permanently | /plugin uninstall recuerd0@maquina |
Failures (bad credentials, offline, rate limit) never interrupt your session — the hooks always exit cleanly and log a one-line entry to ~/.recuerd0/hook-errors.log.
Reading efficiently
Agents can also read efficiently — grep first to find the matching line, then fetch only the surrounding window. Avoids loading the full body of long transcripts and docs.
recuerd0 memory read grep 42 "decision" --context 2 --pretty
recuerd0 memory read lines 42 --start 38 --end 52 --prettyOther AI tools
Any tool that supports HTTP or shell commands can use recuerd0.
| Tool | Integration |
|---|---|
| Cursor | CLI commands in terminal, or REST API via custom tools |
| ChatGPT | REST API via custom GPT actions |
| Windsurf | CLI commands in terminal |
| Custom scripts | REST API directly — curl, Python, Ruby, anything |
Search Tips
recuerd0 uses SQLite FTS5 with a trigram tokenizer. Minimum 3-character queries.
Operators
| Operator | Example | Description |
|---|---|---|
| Term | architecture | Matches documents containing the substring |
| AND | auth AND rails | Both terms must appear |
| OR | meeting OR standup | Either term can appear |
| NOT | design NOT draft | Exclude matching documents |
| Phrase | "project timeline" | Exact phrase match |
| Column | title:architecture | Search only in title |
| Column | body:implementation | Search only in body |
| Grouping | (auth OR session) AND rails | Parentheses for precedence |
Categories
Every memory has exactly one category, picked from a locked four-value enum. Categories are enforced; tags are free-form. Use both — categories for filtering and finding the right kind of memory, tags for finding the right topic.
| Value | Label | When to pick it |
|---|---|---|
decision | Decision | Architecture choices, library picks, tradeoffs with stated reasoning |
discovery | Discovery | Non-obvious findings — gotchas, root causes, patterns, library quirks |
preference | Preference | User-stated rules ("always X", "never Y") |
general | General | Catch-all and default |
general is a fallback, not a default.
Cross-Workspace Links
The same topic often shows up in multiple workspaces — an auth migration touches rails-app, mobile-app, and infra all at once. Memory links (a.k.a. "tunnels") let you express that without duplicating the memory. A link is an undirected, unlabeled "see also" connection between two memories. Links cross workspace boundaries but stay scoped to a single account.
| Workspace | Memory | Topic |
|---|---|---|
rails-app | #42 — "Auth strategy" | Server-side session refactor |
mobile-app | #118 — "Auth strategy (mobile)" | Token storage on iOS / Android |
infra | #204 — "Auth migration runbook" | Rollout, rollback, monitoring |
Linking #42 ↔ #118 ↔ #204 means an agent reading any one of those memories can pull the other two on demand without searching across every workspace. There is no automatic linking — the recuerd0 agent always confirms with you before creating a link, and there is no cardinality limit on how many links a memory can carry.
# Find related memories in another workspace
recuerd0 search "auth strategy"
# Create a link
recuerd0 memory link add 42 --to 118 --workspace 1
# List all links for a memory
recuerd0 memory link list 42 --workspace 1Tag conventions
Tags are separate from categories. Categories are a small enforced enum (see Categories); tags are free-form vocabulary you maintain. Use both. Suggested tag patterns for organizing memories.
| Pattern | Example | Use |
|---|---|---|
| Domain | auth, deploy, testing | What area of the codebase |
| Framework | rails, react, go | Technology stack |
| Type | decision, pattern, debug | Nature of the knowledge |
| Source | transcript, manual, claude-code | How it was created |
| Date | 2026-02, q1-2026 | When it was relevant |
Example Session
A full workflow from context loading to knowledge capture.
# 1. Starting a new task — load relevant context
recuerd0 search "authentication AND patterns"
# 2. Read the most relevant memory
recuerd0 memory show --workspace 1 12
# 3. Do your work with the AI agent...
# 4. Save what you learned
recuerd0 memory create --workspace 1 \
--title "Session auth token rotation" \
--category decision \
--tags "auth,tokens,security" \
--content "# Token Rotation\n\nImplemented automatic token rotation..."
# 5. Link the new memory to a related one in another workspace
recuerd0 memory link add 87 --to 118 --workspace 1
# 6. Archive the session transcript
cat transcript.md | recuerd0 memory create \
--workspace 2 \
--title "Session: token rotation" \
--category general \
--tags "transcript,auth,2026-02" \
--content -
