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, published on the maquina marketplace. It installs the recuerd0 skill — a model-invoked skill that captures, searches, versions, and organizes memories from inside the conversation.
/plugin marketplace add maquina-app/rails-claude-code
/plugin install recuerd0@maquinaPrefer the CLI? recuerd0 skills install drops the same skill into ./.claude/skills — see the CLI page.
The skill runs on demand — ask it to save a session, search your memories, or import a context file — and it also watches the conversation and captures decisions and discoveries as they happen. Every save routes to the right workspace and reports back in one line, so nothing lands without your knowledge.
Proactive capture
The skill watches for capture-worthy moments and saves them without being asked — but only when the knowledge is worth keeping. You stay in control: every save is announced, and cross-workspace links are never created without your confirmation.
| Signal | What gets captured |
|---|---|
| A decision was made | Architecture choice, library pick, or tradeoff with stated reasoning |
| A non-obvious bug was diagnosed | The root cause, once it's understood — not just the symptom |
| You stated a strong preference | "Always do X", "never do Y", "from now on…" |
| A breakthrough discovery | A pattern, library quirk, workaround, or gotcha worth remembering |
| End of a focused session | A curated summary before the context shifts |
Before saving, the skill applies a gate: it only persists knowledge that wouldn't be obvious from reading the code, contradicts a sane default, or cost real time to find. Chitchat, work in progress, and anything already in your CLAUDE.md are skipped. When it does save, it first searches for an existing memory on the topic and adds a new version instead of writing a duplicate.
✓ Saved to workspace rails-app (id 1) as "Auth strategy" [decision] (id 42) [versioned] — so you always know what landed and where.
Workspace routing
Drop a .recuerd0.yaml at each project root and every memory saved from that directory lands in the right workspace — no manual --workspace flag.
workspace: "12"Reading efficiently
The skill reads memories the same way it searches — grep first to find the matching line, then fetch only the surrounding window. That 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 -
