Recuerd0 Now Reads Like a Filesystem

The new Recuerd0 API release teaches the memory store to behave like a filesystem — so AI agents already fluent in grep, glob, and read need no new vocabulary.

Recuerd0 is the persistent memory store for AI coding agents built by Maquina, and this release reshapes how agents read from it. When an AI agent reaches into Recuerd0 for context, the bottleneck has never been storage. It has been how much the agent has to pull back to get to the one fact it needs. A 2,000-line transcript should not have to fit within the agent’s context window to answer “did we decide to use Postgres?” The new release fixes that — and a handful of other long-standing rough edges — by giving the API the same primitives every coding agent already knows: glob, grep, and ranged read.

Here is what is new.

File-tool API: glob, grep, and ranged read on memories

The biggest shift in this release is conceptual. Memories are no longer monolithic blobs that you fetch whole. They are addressable like files.

Glob. The browse and list endpoints accept a title glob pattern. * matches any sequence of characters, ? matches a single character. Combined with tags, source, category, and workspace_id, the agent can narrow a thousand memories down to the dozen worth looking at without reading any bodies.

GET /memories.json?title=Meeting*&tags=design,api&category=decision

Ranged read. GET /workspaces/:id/memories/:id.json now accepts line_start and line_end (1-based, inclusive). The response always echoes total_lines, so the client knows how much memory is available and can compute a tail window in a single follow-up call.

GET /workspaces/1/memories/42.json?line_start=40&line_end=55

There is no head= or tail= parameter — and that is deliberate. line_start=1&line_end=20 is “head 20”; line_start=(total_lines - 19)&line_end=total_lines is “tail 20”. One verb covers both, and the client never has to learn a parallel vocabulary for the same operation.

Grep with line numbers. ?mode=grep&q=<query> switches the same endpoint into a grep response. Instead of returning the body, it returns an array of matches:

{
  "content": {
    "total_lines": 2174,
    "matches": [
      {
        "line_number": 1247,
        "line": "Decided: Postgres for the analytics warehouse, SQLite for everything else.",
        "context_before": ["## Database choice"],
        "context_after": ["Reason: ops simplicity outweighs the JOIN ceiling for our scale."]
      }
    ]
  }
}

Optional context, before, and after parameters control how many surrounding lines to return — capped at 10 each, like grep -C, -B, and -A. The full-text search endpoint (/search.json) supports the same grep mode for cross-memory queries.

The two-step recipe the agent should reach for: first, use grep to locate the line numbers; then issue a follow-up line_start/line_end call to fetch only the surrounding window. A 2,000-line memory becomes a 20-line answer.

Memory categories

Every memory now carries a category: decision, discovery, preference, or general (the default). It is a small thing, but it changes how an agent reasons about what it is reading. A decision is load-bearing — something the team chose and is sticking with. A discovery is a fact about the world. A preference is taste. The agent does not have to infer the difference from prose; it is right there in the metadata, filterable from any list endpoint.

GET /memories.json?category=decision&sort=updated_at

Cross-workspace memory links

Memories can now reference each other across workspaces with first-class “see also” links. The Rails decision in your Backend workspace can point to the deployment write-up in Infrastructure without copying anything. Each memory’s response includes a links_count so the agent knows there is more context one hop away, and dedicated endpoints under /memories/:id/links let it list and traverse them.

This is the connective tissue for context that lives in more than one place — which, in practice, is most context worth keeping.

Workspace wake-up endpoint

A new endpoint, GET /workspaces/:id/context.json, returns a compact “wake-up” payload for an agent starting a fresh session: workspace metadata, recent memory titles, and the highlights an agent should know about before it does anything else. It is the answer to “you are picking up where you left off, here is the room you just walked into.”

Pair it with a Claude Code session-start hook and a new conversation begins with the right context already loaded — no manual recuerd0 memory list dance, no asking the user to repeat themselves.

HTTP caching across the API

All read endpoints now emit ETag and Last-Modified headers and respect conditional requests. A client that sends If-None-Match for a memory it already has receives a 304 Not Modified response with an empty body. For agents that re-fetch the same workspace several times in a session, this is a meaningful drop in tokens shipped over the wire — and a meaningful drop in load on the database.

Grep and ranged-read responses are correctly bypassed by the cache, since they are derived from query parameters that change with each call.

CLI: `recuerd0 memory read`

The recuerd0-cli gains a memory read command group that wraps the new endpoints so a human (or a terminal-bound agent) can use them without hand-crafting URLs:

recuerd0 memory read head 42 --lines 20
recuerd0 memory read tail 42 --lines 20
recuerd0 memory read lines 42 --start 100 --end 140
recuerd0 memory read grep 42 "Postgres" --context 2 --pretty

In --pretty mode, the grep subcommand emits a breadcrumb for each hit, suggesting the exact memory read lines, followed by a call to fetch a window around it. The two-step pattern is right there in the output — no thinking required.

Agent guidance baked in

The Claude Code recuerd0 agent skill now ships guidance for when to use the new primitives, not just how. The dedup-before-write protocol prefers memory read grep over memory show for large candidates. The workflow guidelines tell the agent: when total_lines > ~200, grep first and fetch a window — reserve full reads for memories you genuinely need in their entirety.

The point of teaching these patterns to the agent is the same as the point of adding them to the API in the first place: make the cheap thing the obvious thing.

Documentation

Every endpoint above is documented in the public API reference, and the CLI reference on recuerd0.ai has been updated to match. The grep→fetch-window workflow is called out as a recipe in both places, with worked examples.

Why this release matters

Coding agents are getting fluent. They already know how to use glob, grep, and read — those primitives are how they navigate filesystems every day. Recuerd0’s job is not to invent a new vocabulary for context retrieval; it is to look enough like a filesystem that agents do not have to learn one.

This release is that bet, made concrete. A memory is now something you can grep. A workspace is now something you can wake up in. A long transcript no longer has to fit entirely within a context window just so the agent can quote one line from it.

Get the update

SaaS users on recuerd0.ai: the new endpoints are live now. No action needed.
Self-hosters: pull the latest recuerd0 image (or git pull and redeploy with Kamal). Run migrations to pick up the new category column and the memory_links table.
CLI users: you must update to the latest version to get the new memory read commands — brew upgrade recuerd0-cli (or grab the latest binary from recuerd0-cli releases). Older CLI versions will not expose the new functionality.
Claude Code users: update the recuerd0 plugin from the Claude Code marketplace to pick up the new agent guidance and command reference. Without the plugin update, the agent will keep using the old memory show flow instead of the new grep-first patterns.

Frequently asked questions

How do I grep a Recuerd0 memory? Send GET /workspaces/:id/memories/:id.json?mode=grep&q=<query>. The response returns line numbers and surrounding context instead of the full body. From the CLI: recuerd0 memory read grep <id> "<query>" --context 2.

What is the difference between ranged read and grep mode? Grep mode finds where a string appears (returns matching line numbers with context). Ranged read fetches what is at known line numbers via line_start and line_end. The recommended workflow is grep first to locate, then ranged read to fetch a window.

Do I have to update the CLI and Claude Code plugin? Yes. The new memory read commands ship in the latest recuerd0-cli, and the grep-first agent guidance ships in the updated recuerd0 plugin in the Claude Code marketplace. Older versions will keep working but won’t expose the new endpoints.

What are memory categories used for? Each memory is tagged as decision, discovery, preference, or general. Agents (and humans) can filter by category to find load-bearing decisions without sifting through general notes.

Does HTTP caching apply to grep queries? No. ETag/Last-Modified caching applies to whole-memory and list reads. Grep and ranged-read responses are derived from query parameters and bypass the cache by design.

Announcing Recuerd0 — the original launch and the problem we set out to solve.
Recuerd0 source code is now available — how to self-host under OSASSY.
Maquina open-source projects — the rest of the Rails and AI tooling we maintain.

Recuerd0 is built by Maquina. Source available under OSASSY license.