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

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" \
  --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" \
  --tags "decision,auth" \
  --content "# Auth Strategy\n\nUsing session-based auth with Rails 8 generator..."

# Months later — decision evolved
recuerd0 version create --workspace 1 42 \
  --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.

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

Tag conventions

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" \
  --tags "auth,tokens,security" \
  --content "# Token Rotation\n\nImplemented automatic token rotation..."

# 5. Archive the session transcript
cat transcript.md | recuerd0 memory create \
  --workspace 2 \
  --title "Session: token rotation" \
  --tags "transcript,auth,2026-02" \
  --content -