AI Agents

overview

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 the deep, searchable, cross-project knowledge layer. Your agent queries 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

setup

Project Setup

Create a workspace and configure your project in two steps.

1. Create a workspace

shell
recuerd0 workspace create --name "my-rails-app" --description "Rails 8 monolith"

2. Add project-local config

.recuerd0.yaml
account: personal
workspace: 1

With .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.

CLAUDE.md
## 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

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.

shell
# 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 1

Capture knowledge during a session

When you solve something worth remembering, save it immediately.

shell
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.

shell
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.

shell
# 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

Integrations

Claude Code Plugin

Native integration for Claude Code. Save sessions, search, and manage workspaces without leaving the agent.

install
/plugin marketplace add maquina-app/rails-claude-code
/plugin install recuerd0@maquina

The 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.

project-root/.recuerd0.yaml
workspace: "12"

Hooks stay silent if the 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.

shell
recuerd0 memory read grep 42 "decision" --context 2 --pretty
recuerd0 memory read lines 42 --start 38 --end 52 --pretty

Other 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

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

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.

shell
# 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 1

Links are undirected — linking A↔B is the same as B↔A. Same account only; cross-account linking is rejected. Deleting a memory cascades to remove all its links.

Tag 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

Example Session

A full workflow from context loading to knowledge capture.

full workflow
# 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 -