Indexes Hermes agent sessions into the same shared memory and exposes recall/get tools, allowing past work from Hermes to be recalled alongside other agents.
Publishes local memory as Hugging Face dataset repositories and recalls from remote memories on the Hugging Face Hub, including public or private datasets, through push and recall commands.
Durable memory for your AI coding agents. funes indexes your past sessions across Claude
Code, Codex, pi, and Hermes and lets any agent recall the past decisions, rationale, and findings.
Your memory is a dataset you can publish to the Hugging Face Hub — then any machine, teammate, or
agent can recall from it.
Put a question to a memory and borrow a coding agent to answer it: funes recalls the relevant sessions, hands them over, and you get one grounded answer that names the sessions it drew from — nothing installed. Here it reads the public huggingface/funes-memory dataset named right in the command.
Your agent recalls your past work. The model spontaneously uses funes to recall prior decisions, rationale, and findings mid-task.
One memory across your agents. Index Claude Code, Codex, pi, and Hermes into a single memory; recall spans all of them, and every hit shows which agent it came from.
Your memory is a Hugging Face dataset. Publish it to the Hugging Face Hub; a teammate, another of your machines — or anyone, if you make it public — recalls from it with one flag.
And it happens on its own: with funes added, your agent reaches for recall mid-conversation — no command to run. Here it recalls to answer a question about funes's own design, grounded, naming the session it drew from.
Related MCP server: agent-history-mcp
The installer detects your platform, downloads the matching prebuilt binary,
verifies its tagged release checksum and version, and puts it on your PATH (~/.local/bin by
default):
curl -fsSL "https://huggingface.co/buckets/huggingface/funes/resolve/install.sh?src=readme" | shThen add it to your agent:
funes add claude # or codex, pi, hermesAnother agent? Integrations their authors maintain are listed in
funes-integrations/COMMUNITY.md,
and funes add <id> --from … installs one from wherever it is published.
To build and share your own, start with Writing an integration.
One command onboards you: your agent gets recall and get as tools, and — for Claude, Codex, and
Hermes — funes builds your first index, installs a hook that keeps it current every turn, and (with a
memory bound) publishes at each session boundary. From here you just work. See
docs/add.md for the agents, memory binding, and what a run does; funes status tells
you whether recall is reading your own memory yet.
Tagged binaries and their SHA256SUMS manifest are also available in the
release bucket:
Platform | Binary |
Linux x86_64 |
|
Linux aarch64 |
|
macOS Apple Silicon |
|
The checksum detects corrupt, truncated, or mismatched release downloads. Because the binary and checksum share the same bucket, it does not authenticate the bucket itself.
Already installed? funes update replaces the binary in place with the latest build for your
platform (--force reinstalls the current one), then brings your agent integrations to their newest
release; funes status tells you when a newer release is out. To build it yourself, see
Building from source.
funes names itself to the Hub: the User-Agent of its Hugging Face requests carries its version and
an anonymous install id. The id is a random UUID kept in ~/.funes/install-id, created on the
first run. It derives from nothing (not your hostname, user, hardware, or Hugging Face account) and
only lets the project count installs and active installs, local-only ones included. It goes
nowhere but the Hub. Set DO_NOT_TRACK=1 or FUNES_NO_TELEMETRY=1 to leave it out. Deleting the
file starts a new one. The installer's own downloads say only which script revision and platform
they are for.
Your memory isn't tied to one tool. Because Claude Code, Codex, pi, and Hermes all index into a single memory, you can switch agents without losing anything — start a task in Claude Code, pick it up in Codex next week, and each one recalls the entire history, not just its own sessions (every hit shows which agent it came from). Another agent can join by writing its sessions as funes JSONL turns files.
Models work the same way. funes runs pinned local embedding and reranking models, but no generative model of its own: you reason with whatever your agent uses — through pi, any local model or one served through the Hugging Face router. Switch models between sessions and the memory doesn't move.
Your local memory is a dataset, and it shares the way one does: publish it to a Hugging Face dataset repo you own and it becomes an artifact on the Hub like any model or dataset — owned by your account or org, gated by your token, readable by whoever you say. Not just the code of a project, but the process behind it — the decisions, dead ends, and rationale — becomes something an agent can recall.
Dataset repositories created by funes are private by default. Existing repositories retain their current visibility, and making a funes-created memory public is a deliberate change on the Hub.
Bind your host to a memory, funes bind <user|org>/funes-memory or the memory named when you add
an agent, and every agent recalls from it and keeps it current on its own; or run the two commands
directly:
funes push <user|org>/funes-memory # publish your local memory's new chunks
funes recall "..." --memory <user|org>/funes-memory # read any remote memory for one callThat second form is how you read someone else's published memory on a topic, without touching your own setup. Publishing is guarded: funes redacts credentials at index time, and a separate, always-on gate refuses to push any chunk that still contains a secret. And because a published memory is just a dataset, you can try recall right now, before indexing anything of your own:
funes recall "why is funes append-only" --memory huggingface/funes-memoryAnd to get an answer rather than ranked passages, borrow an agent for one question — nothing installed:
funes ask claude "why is funes append-only" --memory huggingface/funes-memory # or: funes ask codexSee docs/push.md for publishing, the secrets gate, selecting what to publish, and inspecting a memory; docs/ask.md for grounded answers; docs/hub-caching.md for how remote recall caches to local speed.
funes add wires all of this into your agent; each command is also usable on its own. Browse the
workflow-oriented documentation index for the complete guides.
Command | Docs |
| docs/add.md — supported agents, integration lifecycle, memory binding, generic MCP clients, and hooks |
| docs/index.md — build/update the memory and compact it; sources, incremental, flags |
| docs/recall.md — recall passages and drill into them |
| docs/sessions.md — list sessions, digest one, find a literal in one |
| docs/ask.md — borrow an agent for a grounded answer |
| docs/push.md — publish and share a memory |
| installation and updating — replace the installed binary with a verified release, and update the agent integrations |
The per-turn indexing and session-boundary publishing the hooks run are detailed in docs/automation.md.
funes add runs one loop: index what you've done, recall it when it matters — and index what
you just did, so it's recallable next time. Both halves are one deterministic pipeline: each source
is parsed into a generic turn/block shape, chunked, written to a local Lance dataset, and embedded
with a pinned local model; recall fuses vector + BM25 search, and reranks the pool with a cross-encoder.
Integrations convert each agent's transcripts into the shared turns format.
Adding an agent means publishing an integration of your
own; the indexing and query pipeline already reads that format.
funes shapes its output for agents, not people — so to put a question to a memory yourself, borrow
an agent: funes ask recalls from the memory and answers grounded in what it finds, installing
nothing. funes recall prints the raw ranked passages behind an answer, and funes get reassembles
any cited turn in full.
docs/index.md — sources, progress, and incremental indexing.
docs/recall.md — retrieval, drill-down with get, and reading a shared memory.
docs/sessions.md — browsing a memory by session: sessions, sketch, scan.
docs/ask.md — borrow an agent for a grounded answer, nothing installed.
docs/automation.md — the per-turn hooks that keep it all fresh.
Needs a Rust toolchain and protoc — lance's build scripts compile protobuf at build time
(the finished binary does not need it). Install it one of two ways:
# System-wide:
sudo apt-get install -y protobuf-compiler # Debian/Ubuntu
brew install protobuf # macOSThen cargo build --release (binary at target/release/funes); cargo test runs the suite. The
integration test downloads the embedder/reranker weights on first run.
Inference (embedding + reranking) runs on a built-in backend — Accelerate on macOS, pure Rust on Linux — so the default build has no ML runtime dependency and runs on any glibc ≥ 2.35 (Ubuntu 22.04). On macOS 15 or later, indexing embeds and recall reranks on the GPU through Metal, falling back to the CPU where no GPU starts. An ONNX Runtime backend is available as an opt-in variant:
cargo build --release --no-default-features --features onnx # ONNX backend instead
cargo run --release --features onnx --example bench_backends # A/B both backendsEach memory names its embedding model, and funes embeds a query with the model of the memory it searches. A memory holds one model's vectors: funes indexes into it with that model, and refuses to push another model's vectors into it. To change it, rebuild from the transcripts (the memory is a disposable derived artifact — the raw text is retained in every row). This is separate from the model you reason with, which is free to change.
Subagent transcripts (.../subagents/agent-*.jsonl) are indexed too.
"To think is to forget differences, generalize, make abstractions." — Jorge Luis Borges, Funes the Memorious
Why funes is built the way it is — and how it compares to other memory tools — is documented in
docs/RATIONALE.md.
funes is licensed under the Apache License 2.0.
Read one session's turns as they were written — whole blocks, splits reassembled, nothing ranked or summarized. Typically the follow-up to a search verb: expand a result into the turns around it. Sessions run to thousands of turns: read the stretch you need, not the session.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last turn to read, as the session's own seq. Omit it to read a fixed span from `from`; every reply names the range it covered. | |
| from | No | First turn to read, as the session's own seq, which a hit's `→ get` line gives you. Defaults to the session's start. | |
| memory | No | Memory to read for this call, as it stands — the one the hit's `→ get` line carries, and none when it carries none, so the drill-down reads what the search read. Omitted, the server's memory, where a session this host has not finished pushing is read from the local memory. | |
| session_id | Yes | Session id from a recall hit's `→ get` line |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose non-obvious traits: content is returned as written, splits are reassembled, and nothing is ranked or summarized. However, it says nothing about cost/latency on huge sessions, error behavior for missing sessions, or the read-only guarantee beyond the verb 'Read'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool returns, then when to use it, then a scoping warning. No redundant restatement of the name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with complete schema coverage and no output schema, the description covers data fidelity, scoping, and the search-to-get workflow. Return structure is only partially sketched (whole blocks, named ranges), which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents session_id, from, to, and memory in detail. The description reinforces range-scoped reading ('read the stretch you need') but adds no per-parameter meaning beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action — reading one session's turns verbatim, with splits reassembled and no ranking or summary — which separates it from the search-oriented siblings (recall, scan). The generic name 'get' is compensated by this textual specificity, though it does not name the exact sibling it follows up on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Typically the follow-up to a search verb: expand a result into the turns around it' gives a clear when-to-use context, and 'read the stretch you need, not the session' sets a scoping constraint for large sessions. It stops short of explicitly naming recall/scan as the alternative or stating when-not-to-use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search over the user's past AI agent sessions: describe what you are after, get back the verbatim passages — what was decided, tried, measured or investigated. Call it when they refer to earlier work, or when you are about to re-derive something a session may already have settled. Call it too before claiming that something was never built, was dropped, or was never discussed: the code cannot show that, only the sessions can. Ranked top-k, so it gives you a foothold on a topic, not every session touching it. Ranking weighs relevance, not age: for the latest word on a topic, or one stretch of time, bound it with since/until. Each hit is a passage you will read: k is the token cost, candidates the reach, and a pool larger than k is reranked, at seconds of latency that grow with the pool, so the reach can grow without the reading.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Hits returned (default 8). Each is a verbatim passage of a few hundred tokens, so `k` is what a call costs to read. | |
| repo | No | Restrict to turns whose checkout resolved to this repo, as `owner/name` | |
| role | No | Restrict to a role, as the turns carry it (an agent's turns say user | assistant | tool | system) | |
| query | Yes | Natural-language description of what to recall from past sessions. A query matches best in the language they are written in, which `status` reports. | |
| since | No | Restrict to turns on or after this date, `YYYY-MM-DD` | |
| until | No | Restrict to turns on or before this date, `YYYY-MM-DD` | |
| memory | No | Memory to read for this call, as it stands — `<org>/<repo>`, an `hf://…` URI, a local path, or `local`. Omitted, the server's memory, with this host's turns not yet pushed to it when the host is bound to it. | |
| harness | No | Restrict to a harness facet, as the turns carry it (`claude` also matches the older `claude_code`) | |
| neighbors | No | Adjacent chunks attached to each hit for context; 0 returns the hits alone. | |
| block_type | No | Restrict to a block type: text | thinking | tool_use | tool_result | |
| candidates | No | Size of the fused pool the hits are cut from (default 30): how far the search looks. Larger than `k`, the pool is reranked by the cross-encoder before the cut, which costs seconds and grows with the pool, so `k` can stay small while the search looks deep. A pool of `k` rows or fewer is read whole, in the fused order. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description still discloses the traits that matter: ranking is relevance-weighted not recency-weighted, results are top-k and therefore not exhaustive, a reranked pool costs 'seconds of latency that grow with the pool', and `k` is the read cost in tokens. It also tells the agent what a hit physically is (a passage it will read) rather than leaving the return shape opaque despite there being no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose and usage are front-loaded, and every sentence carries information about either when to call or how the tool behaves. The final sentence is the weakest — 'so the reach can grow without the reading' restates the schema's own k/candidates wording in a denser form, adding length without new meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, no-annotations, no-output-schema tool this covers the critical ground: what it searches, what comes back, when to reach for it, and the latency/cost tradeoff. Filter parameters like `repo`, `role`, `harness`, `block_type`, `neighbors` and `memory` are left entirely to the schema, which is acceptable at 100% coverage but means the description alone would not let an agent reason about narrowing a search.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, and here the description genuinely adds a mental model beyond field definitions: `k` as what the call costs to read versus `candidates` as how far the search looks, plus the rule that a pool larger than `k` triggers cross-encoder reranking. It also explains why `since`/`until` exist (ranking ignores age). Some of this echoes schema text almost verbatim, which caps it below 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening clause gives a specific verb and resource: 'Semantic search over the user's past AI agent sessions', and it adds what comes back ('verbatim passages — what was decided, tried, measured or investigated'). It is unmistakably different from get/scan/sessions/sketch/status, but it never names a sibling to route the agent explicitly, which is what separates a 5 from a 4.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Three concrete triggers are given: when the user refers to earlier work, when about to re-derive something a session may have settled, and before claiming something was never built/dropped/discussed. The scope limitation ('a foothold on a topic, not every session touching it') also tells the agent not to expect exhaustive coverage. What's missing is an explicit exclusion or a named alternative for cases the tool is wrong for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find every occurrence of a literal string in one session — exhaustive, unranked, in reading order. For when you already know the wording and want where it occurs, rather than what a topic is about. Scope is one session and one spelling: a zero result clears only that.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last turn to scan, as the session's own seq. Omit to scan to the end of the session. | |
| from | No | First turn to scan, as the session's own seq. Omit to start at the session's beginning; pass the seq a capped scan told you to continue from. | |
| memory | No | Memory to scan, as it stands — `<org>/<repo>`, an `hf://…` URI, a local path, or `local`. Omitted, the server's memory, where a session this host has not finished pushing is read from the local memory. | |
| needle | Yes | The literal string to find. Not regex — a pattern that silently matched nothing would read as a clean result. | |
| context | No | Characters of surrounding text shown on each side of a match | |
| session_id | Yes | Session to scan — the id from a `sessions` row or a recall hit's `→ get` line | |
| ignore_case | No | Match regardless of case |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses result ordering ('unranked, in reading order'), completeness guarantees ('exhaustive'), and the negative-result semantics ('a zero result clears only that session and spelling') — a genuinely non-obvious caveat. It stops short of describing whether output can be capped or paginated, even though the schema's 'from' description alludes to a capped scan needing continuation, and it says nothing about the response shape; those are the remaining gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with what the tool does before the when-to-use clause and the scope caveat. No filler, and the ordering of information matches the order an agent needs it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter, no-annotation, no-output-schema tool, the description covers purpose, ordering, literal-vs-regex, and the crucial limits of a zero result. The one meaningful omission is that it never says results may be capped or how continuation via 'from' works, leaving the agent to discover that from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented in structured form, setting the baseline at 3. The description reinforces two points beyond the schema — that matching is literal, not regex, and that scope is one session and one spelling — but adds nothing about 'from'/'to' seq semantics or 'context' sizing that the schema does not already say.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Find every occurrence of a literal string in one session') plus scope qualifiers (exhaustive, unranked, reading order). It gestures at the sibling it is not — topical lookup via recall — with 'rather than what a topic is about', but never names 'recall' or the other siblings, so differentiation is inferential rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear selection rule: use this when you already know the wording and want locations, not when you want to know what a topic is about. The exclusion is stated as a condition, though the alternative tool is not named, so the agent must map the contrast to 'recall' itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate a memory's sessions, oldest first. Metadata only — when it started and when its last indexed turn was, harness, repo, turn count, id, and the prompt each opened with, which is the ask a session started from, not what it became. Filter by repo or date to get the session ids the other verbs take; a whole memory can run to thousands of rows.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Keep only sessions whose checkout resolved to this repo, as `owner/name` | |
| limit | No | Rows to list, keeping the most recent. More than the maximum cannot fit in one reply — walk with `offset` instead. Zero is an error, not every match. | |
| since | No | Keep only sessions that started on or after this date, `YYYY-MM-DD` | |
| until | No | Keep only sessions that started on or before this date, `YYYY-MM-DD` | |
| memory | No | Memory to list, as it stands — `<org>/<repo>`, an `hf://…` URI, a local path, or `local`. Omitted, the server's memory, with the sessions this host has not finished pushing listed from the local memory when the host is bound to it. | |
| offset | No | Skip this many of the most recent matches before taking `limit`, to walk a listing back through time. The closing line names the offset that continues, and a given offset always names the same session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description usefully establishes a read-style enumeration, oldest-first ordering, metadata-only results, and potentially large result sets. It does not explicitly discuss permissions or failures, but those omissions are modest for this listing operation and pagination behavior is covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the operation and ordering, then moves efficiently through result scope and usage. Its middle sentence is dense, but the clauses provide meaningful field and prompt semantics rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Together with the fully documented schema, the description supplies what an agent needs to invoke the tool: resource, scope, ordering, returned metadata, filtering rationale, and scale considerations. The absence of an output schema is substantially offset by the explicit enumeration of returned fields, while the input schema covers memory selection and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including formats, defaults, filtering, and pagination, so the schema already does the heavy lifting. The description adds the purpose of repo and date filtering—obtaining ids for other verbs—but little additional parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource—enumerating a memory's sessions—and clarifies ordering, metadata-only scope, and the exact fields listed. Explaining that the opening prompt is what a session started from, rather than what it became, further prevents misinterpreting the result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete workflow: filter by repo or date to obtain session ids consumed by other verbs, and warns that an unfiltered memory may contain thousands of rows. "Metadata only" also signals when not to use it for session contents, though it does not name the specific sibling tool to use next.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What one session was about, worked on, and ended up at: the passages most distinctive within it, verbatim, always including its opening ask and its last word. Takes a session id; there is no query. Enough to tell the user what a session was, in one call; not a way to find a particular thing in it.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last turn to digest, as the session's own seq. | |
| from | No | First turn to digest, as the session's own seq. Digest a long session in windows to get coverage proportional to its length rather than a fixed sample of it. | |
| units | No | How many distinct places to show — breadth (default 8, maximum 40). Also held to what `max_chars` can render at 240 characters apiece, and any narrowing is reported in the reply. | |
| memory | No | Memory to read for this call, as it stands — `<org>/<repo>`, an `hf://…` URI, a local path, or `local`. Omitted, the server's memory, where a session this host has not finished pushing is read from the local memory. | |
| max_chars | No | Total characters to render — cost (default 8000, maximum 40000). More than that is a reply no caller receives. | |
| session_id | Yes | Session to digest — the id from a `sessions` row or a hit's `→ get` line |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral load. It does disclose a genuine output guarantee (verbatim passages, always includes the opening ask and last word) and the hard constraint of no query, but it does not state that this is a non-mutating read, nor describe pagination, ordering, or failure behavior for an unknown session id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with what the caller receives before the scoping caveats. The opening clause ('what one session was about, worked on, and ended up at') is slightly convoluted but every clause carries information; nothing pads.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter read tool with no output schema, the description plus the very detailed schema fields cover cost/breadth limits, windowing for long sessions, and what the returned passages look like. What's missing is modest: no statement of read-only safety and no mention of error behavior on a bad session id.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter descriptions are unusually rich (defaults, maxima, the windowing advice, the narrowing report), so the schema does the heavy lifting. The description adds only the `session_id` meaning and the 'no query' absence; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource and result shape — 'the passages most distinctive within it, verbatim, always including its opening ask and its last word' — so an agent knows this returns a session digest, not a search hit. It excludes the search use case ('there is no query', 'not a way to find a particular thing in it'), which separates it from recall/scan, though it never names the sibling to use instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear when-to-use ('enough to tell the user what a session was, in one call') and an explicit when-not ('not a way to find a particular thing in it'), plus the schema's `from`/`to` docs steer long sessions to windowed digests. It stops short of naming which sibling handles the lookup case, leaving that inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health and size of a memory: indexed chunks, the languages its sessions are written in, local chunks awaiting embedding, source sessions awaiting indexing, and for a remote this host pushes to what it has yet to push. Call it when a read comes back empty or thinner than expected — it says whether the memory is the problem rather than the call.
| Name | Required | Description | Default |
|---|---|---|---|
| memory | No | Memory to inspect — `<org>/<repo>`, an `hf://…` URI, a local path, or `local`. Omitted, the server's memory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does substantial work: it makes clear this is a non-mutating diagnostic that reports state rather than changing it, and it spells out each diagnostic dimension returned. It does not address cost, whether the call is expensive on large memories, or how it behaves when the memory does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The what-it-reports content is front-loaded and the usage condition follows, so the reader hits the essential information first. The long enumeration of diagnostics is dense but each item is distinct and informative. Two sentences, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-optional-parameter tool with no annotations and no output schema, the description substitutes effectively for a missing return-value spec by enumerating the diagnostic fields. The default-memory case is covered by the schema, and the diagnostic framing tells the agent how to interpret results. Little an agent needs to call this correctly is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter's description already lists every accepted form (<org>/<repo>, hf:// URI, local path, local) plus the omitted-default behavior. The prose adds only a passing hint about remotes this host pushes to, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific resource and enumerates exactly what is reported: indexed chunks, session languages, chunks awaiting embedding, sessions awaiting indexing, and remote push lag. That is far more than a restatement of the name 'status'. It stops short of naming any sibling tool, so an agent must infer the boundary with get/recall/scan rather than being told.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Call it when a read comes back empty or thinner than expected" gives a clear triggering condition and implicitly positions it after a read tool. That is real when-to-use guidance with an implicit alternative. It does not name a specific sibling or state any when-not condition, which keeps it out of the top band.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.10.0getrecallscansessionssketchstatusScored across 6 tools
The tools mostly have distinct roles: recall is semantic search across sessions, scan is literal string search within one session, sessions lists metadata, get reads raw turns, sketch summarizes a session, and status reports health. The only mild overlap is between get and sketch, since both read one session, but the descriptions make their different purposes fairly clear.
All tool names are single lowercase words with no mixed casing or underscores, which is a consistent convention. The set mixes verbs (get, recall, scan, sketch) with nouns (sessions, status), so it does not follow a strict verb_noun pattern, but it remains readable and predictable.
Six tools is well within the appropriate range and each tool covers a distinct retrieval or diagnostic operation. There are no obviously redundant tools, and the surface is compact for a memory-retrieval server.
The surface covers the core read-only lifecycle for past sessions: enumerate, semantically search, literal scan, read raw turns, summarize a session, and check memory health. Minor gaps could exist around managing multiple memories or write/forget operations, but for a retrieval-focused server the coverage is strong.
Shared memory for AI tools: save once, recall word for word from Claude, ChatGPT, Codex or Gemini.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory for AI agents. Search, store, and recall across sessions.
Recall (recall.it) — your AI knowledge base / 'second brain'. Via the official API: semantic search