Persistent AI memory over MCP, cataloged as Open Knowledge Format (OKF) Markdown. Zero runtime dependencies, no network, no model call.
Librocat demonstrates solid tool design with 17 well-named, verb-prefixed tools (search, get_concept, list, ingest, update, delete, etc.). All tools have descriptions (avg ~100 chars, within baseline 34-392 range). Input schemas are present and typed with Zod validation. However, output schemas are NOT documented, the code shows tool registration but no explicit return type documentation visible in the source. Parameter descriptions are present but some are terse (e.g., 'Concept id' for the `id` param in get_concept). Error handling is minimal, no recovery guidance, no categorization of retryable vs fatal errors. The tool composition is excellent (each tool has one responsibility, names are clear), but the lack of documented output schemas and sparse error guidance prevent a higher score.
Delete one concept (weeding). Inbound links from other concepts become broken links.
Finding aids: one shelf list per directory; Local can write them as index.md.
Read one concept in full: frontmatter, body, tags, and metadata.
A breadth-first subgraph of concepts around `id`, as nodes and edges.
Revision history: Git history in Local, the revisions table in Cloud.
Create an OKF concept and index it. Returns its id. If `id` is given and already exists, that concept is overwritten in full; use `update` to change only some fields. If `id` is omitted it is derived from the title (else the body, else the type) and de-duplicated with a numeric suffix. To write many concepts in one call (for example, one document turned into several concepts), pass `concepts`: each item is written on its own and the result lists, per item, the id or the error.
Output schemas not documented. Tools return JSON-serializable values but no explicit return type documentation is visible in the source code. LLMs cannot plan downstream tool calls or extract specific fields without knowing the response structure.
Error handling lacks recovery guidance. Tools throw errors but do not provide actionable next steps (e.g., 'Concept not found. Try search() with a partial title.' or categorization of retryable vs fatal errors). Agents cannot self-correct.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | 2026-07-28+ | v2 |
Walk a code repository and write one OKF concept per source file into the bundle. Returns the concepts written.
List concepts (metadata only), optionally filtered by type, tag, status, or shelf (the leading directory of concept ids, e.g. 'acme').
Direct links of a concept: outbound (it links to) and inbound (links to it).
Rebuild the index from the files on disk in Local. The Cloud-mode bridge implements it too, as a no-op (nothing to rebuild).
Move a concept to a new id and rewrite every inbound link. The old id is deleted.
Search the library. Returns ranked concepts with match snippets.
Set (or remove with null) one preferred tag's relations.
Check freshness and see the live type/tag vocabulary.
The tag thesaurus (controlled vocabulary).
Patch a concept: change only the fields you pass. Omitted fields are left alone. `body`, `title`, `description`, `tags`, `type`, and `status` are standard; `extra` is a map of custom frontmatter keys (set a key to null to delete it). `superseded_by` retires this concept in favor of another (implies deprecated).
The CREW/MUSTIE weeding report (never retrieved, deprecated, broken, orphans, blank records).
Destructive operations (delete, rename, ingest_repo) lack confirmation or dry-run support. Agents can irreversibly delete concepts or rewrite links without a safety gate.
Some parameter descriptions are terse (e.g., 'Concept id' for `id` in get_concept, 'Direct links of a concept' for neighbors). Descriptions should explain WHAT the tool does, WHEN to use it, and any prerequisites.
No pagination guidance for list-returning tools. search() and list() accept limit but do not document total count, next_cursor, or offset behavior. Large result sets risk context window exhaustion.