Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@engram search for auth migration decisions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your AI forgets everything when the chat ends. Engram helps it remember. Free, private, runs on your own computer, and keeps every word exactly as you wrote it.
On Monday you spend an hour with Claude working out why the login system leaks memory, and you decide to switch libraries. On Friday you open a new chat and ask "why did we drop Passport again?"
It has no idea. The conversation is gone, and so is the reasoning.
The same thing happens with everything you tell an AI: your sister's birthday, the bug you already fixed, the reason a setting is the way it is. Every new chat starts from zero.
Engram is a memory that outlasts the chat. It saves your notes, files and conversations, and when you ask a question later, it finds the right one, even if you phrase it completely differently.
Related MCP server: memory-mcp
Two ordinary notes go in:
notes/decisions.md We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
notes/personal.md My sister Maya's birthday is June 14. She loves anything
with sunflowers.engram mine notes --wing lifeDays later, ask in your own words. None of these questions share a sentence with the notes:
$ engram search "why did we change the auth library"
1 life/notes We switched from Passport to Lucia on March 3 because
Passport sessions kept leaking memory under load.
$ engram search "gift idea for Maya"
1 life/notes My sister Maya's birthday is June 14. She loves anything
with sunflowers.Hook it up to Claude and it does this by itself: Claude looks things up in Engram when it needs them, and Engram saves your Claude Code sessions automatically.
You need Python 3.9 or newer (3.11 to 3.14 is best). Check with python3 --version.
1. Install
pip install engram-chateauOn PyPI the package is called
engram-chateau, but the command you type is justengram. (A different, unrelated package already owns the nameengram.)
2. Give it something to remember
engram mine ~/Documents/notes --wing notes # any folder of notes, docs or codeThe first run downloads a small language model (about 80 MB) that lets Engram understand meaning. After that, everything works offline.
3. Ask it something
engram search "what did I decide about the database"That's all you need to try it.
Engram works with any app that speaks MCP, the standard way AI apps plug in tools. One command adds it:
engram connect cursor # or: claude-desktop, windsurf, vscode, gemini, codex, zed, lm-studio
engram connect all # every supported app on this computer
engram connect # list them, with ✓ next to the ones you haveIt adds Engram to that app's settings (keeping everything else, with a .bak backup) and tells you how to restart the app. Run it again any time; it changes nothing the second time.
App | Setting it writes |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
VS Code (Copilot agent mode) | your user |
Gemini CLI |
|
Codex CLI |
|
Zed, LM Studio | prints the snippet to paste |
Every app then has 31 engram_* tools: recall, search, remember, correct an outdated memory, link a conclusion to its evidence, explain why a memory says what it says, a topic's history, a knowledge graph of people and facts, and more. On connect, Engram also tells the AI how to use them: check memory before answering anything that depends on past work, save decisions, and correct rather than contradict. (Apps decide whether to pass that guidance to the model; most current ones do.) Ask "remember that we use tabs in this repo", "what did we decide about auth?" or "we moved to PostgreSQL, update that".
Claude Code gets the most: memory that works without being asked.
engram connect claude-code # prints the one-line `claude mcp add` command
engram install-hooks --apply # then restart Claude Codeinstall-hooks adds three Claude Code hooks to ~/.claude/settings.json (your existing settings are kept, with a backup):
Auto-recall. Each time you send Claude a message, Engram searches your memory first. If something clearly relevant turns up, Claude gets a short note with up to 3 memories before it answers, current versions first (with what they replaced and why) and outdated ones labelled. You ask "why did we drop Passport?" in a brand-new chat, and Claude already knows. Nothing is added when nothing is relevant, a memory isn't repeated within a session, and it takes about a second once warm (the first message after your computer starts it can take several seconds while it loads).
Project-aware. Memories are filed under the project you're working in (the git repo or folder name), and recall shows that project's memories first; other projects' notes only appear when they match very closely.
Auto-save. Every file Claude edits is saved.
Save before compacting. The conversation is saved before Claude Code compacts it.
Preview what auto-recall would hand Claude with engram recall "your message". Run engram install-hooks without --apply to see the settings instead of applying them, or add --no-recall to skip auto-recall.
Any other MCP app: point it at the command engram-mcp (or python -m engram.mcp_server). Engram is also listed in the official MCP registry as io.github.TushaeBXN/engram.
Apps that don't speak MCP (Open WebUI, n8n, your own scripts) can use Engram over a small local web API:
engram serve # http://127.0.0.1:7742, the same tools and rules as MCPPoint the app at http://127.0.0.1:7742/openapi.json; every tool is described there. Or call it directly:
curl -s localhost:7742/v1/tools/engram_recall -H 'Content-Type: application/json' \
-d '{"message": "why did we drop Passport?"}'Memories are private, so it is strict by default. It listens on localhost only, and refuses requests that look like they come from a web page or through a proxy. To reach it from another machine, use engram serve --host 0.0.0.0: that always requires a token (created on first use in ~/.engram/server/token, never printed), sent as Authorization: Bearer <token>. engram serve --token requires one even on localhost. No CORS headers are ever sent, so a web page can't talk to it.
Teach any coding agent to use it. skills/engram/SKILL.md is a ready-made agent skill: when to recall, save and correct, and how to explain a conclusion. Install it with npx skills add TushaeBXN/engram (or copy the file).
uv tool install engram-chateau # or: pipx install engram-chateau
engram init ~/myproject # guided setup: your AI's identity, a default wing, then saves the projectBoth put engram and engram-mcp on your PATH without touching your system Python.
🧑💻 Developers using Claude Code. Engram quietly saves the files Claude touches and the conversations behind them. Months later, "why is the retry limit 7?" brings back the actual discussion, not a guess.
🤖 People building an AI companion or agent. Give your bot a memory of its own: what it has learned about you, a diary, and a knowledge graph of people and facts ("Kai works on Orion, since June"). It all runs offline in a few lines of Python. Engram started life as exactly this, the memory of a personal companion app.
📚 Writers, researchers and note-takers. Point it at a folder of notes, an Obsidian vault, or Notion or Linear exports, and search across all of it by meaning: "that idea I had about pricing tiers".
🔒 It's yours. Everything lives in one folder on your computer (~/.engram/). No account, no cloud, no API key, no tracking.
📝 It keeps your words. Most AI memory tools have an LLM rewrite your conversations into short "facts" and throw the original away. Engram stores the original text and finds it again. Nothing gets lost in a summary.
🧠 It understands what you mean. It finds "we switched from Passport to Lucia" when you ask about "changing the auth library". It also matches exact names and numbers (INV-20931), and understands time: "two weeks ago", "in June", "on May 8".
💸 It's free to run. It needs no LLM to save or search, so there are no per-message costs and nothing to rate-limit.
🎯 It's accurate. On the two standard tests of AI memory, it beats the best published no-LLM results (numbers below).
📖 You can read all of it. About 10,000 lines of plain Python, MIT licensed. If you want to know exactly what happens to your data, you can.
🔄 It knows when it's out of date. When a decision changes, the new memory is marked as replacing the old one. Search gives you the current answer first, and the old one stays below it as history, with when and why it changed.
🔑 It can hide secrets for you. Turn on redact_secrets and API keys, tokens and passwords are blanked out before anything is written to disk.
Engram files memories the way you'd organise a big house: one wing per person or project, a room per topic, a hall per kind of memory, and inside, drawers holding the original text.
Wing – a person or project ("myapp", "life")
└── Room – a topic ("auth-migration")
└── Hall – the kind of memory (facts, events, discoveries, preferences, advice)
└── Drawer – your original text, word for wordYou don't have to manage any of this; Engram sorts things as it saves them. When you search, it weighs several clues together:
Clue | What it does |
Meaning | Finds text that means the same thing, even in different words |
Exact words | A full-text index catches names, numbers and rare words the meaning search misses |
Time | "What did I buy two weeks ago?" or "what happened in June?" favours memories from then |
Passing remarks | Notices things you mentioned in passing ("I've been sleeping badly") so later questions find them |
Recency | Leans slightly toward newer memories; pinned ones never fade |
Reranker (optional) | A small local model re-reads the top 20 and puts the best one first |
At the start of a session, Engram can also hand the AI a small "wake-up" note (who it is plus key facts: pinned ones first, then the newest, about 120 tokens by default), so it never starts completely cold.
In March you note that the app stores everything in SQLite. In April you move to PostgreSQL. Most memory tools now hold two contradicting notes and return whichever matches the question best.
In Engram, you (or Claude, or your agent) record the change once:
engram correct file-05aa607a "We migrated the app from SQLite to PostgreSQL on April 9" --reason "SQLite locked under concurrent writes"From then on, search puts the current answer first and keeps the old one, clearly labelled, right below it:
$ engram search "which database does the app use"
1 c6e0b7b4 [current, replaces file-05aa607a] We migrated the app from SQLite to PostgreSQL on April 9…
2 file-05aa607a [outdated → c6e0b7b4] Decision: the app stores everything in SQLite because…engram history file-05aa607a shows the whole story: what it said, what replaced it, when, and why. Nothing is ever silently deleted. Old evidence stays searchable, and a mistaken correction can be undone with engram supersede <id> --undo.
Engram never decides by itself that one note contradicts another. Deciding what is true is the job of whoever is using it. When Claude saves a memory, Engram points out existing memories it might update, and Claude decides.
A memory can say what it rests on and where it came from, so a conclusion never floats free of its evidence:
engram source 903294e5 primary --ref "U.S. Const. art. I, § 2" # where a memory came from
engram link c9422f65 based_on 903294e5 --reason "constitutional text"
engram link c9422f65 derived_from 2da14213 # also: contradicts, supersedesSources are user (you said it), primary (an original document, law, ruling or dataset), secondary (reporting or analysis), tool (a search or program result) and inference (an AI's own conclusion). Inferences stay labelled as inferences.
engram why <id> explains any memory: its source and date, whether it is a record or an inference, the evidence behind it, whether that evidence has since been corrected or disputed, earlier versions and their evidence, and, with --query, why search ranked it:
$ engram why c9422f65
c9422f65-… amy/views 2026-10-20
My view: population apportionment is the baseline; the 2025 map changes the state's representation.
Source: AI inference. Type: an inference.
Evidence
based_on 903294e5 2026-10-20 primary source, U.S. Const. art. I, § 2
Article I, Section 2: Representatives shall be apportioned among the several States…
derived_from 2da14213 2026-10-20 secondary source OUTDATED → 914e0cb2
Report: the legislature adopted a new map in 2025.
Needs review
• evidence 2da14213 was corrected (current version: 914e0cb2); check whether this still holdsengram check lists everything like that across your memory: conclusions whose evidence was corrected or disputed, inferences with no evidence, conflicts nobody has settled, links to deleted memories. It changes nothing. When a position is revised, the old one keeps the evidence it had, so you can always see what the earlier view rested on and what supports the new one.
Backups. engram export backup.json.gz puts every memory, correction, knowledge-graph fact and diary into one file. engram import backup.json.gz restores it on another computer, after checking the whole file first: if anything is wrong, nothing is changed. The format is documented in docs/backup-format.md.
Researchers test AI memory with two public benchmarks. Each gives the system long chat histories and asks questions whose answers are buried somewhere inside. The score is how often the system finds the right conversation.
Benchmark (default settings, no LLM) | Engram |
LongMemEval: 500 questions, right conversation in the top 5 | 98.8% |
LoCoMo: 1,986 questions, answer's sessions in the top 10 | 92.1% |
In plain terms: ask Engram 500 questions about months of chat history, and for 494 of them the right conversation is in its top 5 results. It gets there with a small model that runs on a laptop, no LLM and no API. These tests measure finding the right conversation. They don't measure whether corrections, evidence links or recall notes make an AI more accurate; benchmarks/trust_eval.py checks those, and the results are listed below.
Does it keep memory trustworthy? Those tests don't cover corrections, the notes handed to a model, or crashes, so benchmarks/trust_eval.py checks them. On its own (author-written, deliberately small) scenarios, in the current version:
Result | |
After a fact changes, the current version comes first | 20 of 20 questions (4 of 20 with no correction history) |
Auto-recall note size vs. pasting every memory | 92 tokens vs. 5,134 |
Auto-recall note contains the answer | 17 of 20 (a plain top-5 search: 19 of 20) |
Auto-recall speaks up when nothing relevant is stored | 0 of 20 times |
Memory files left half-written after 40 forced crashes | 0 (10 before 1.10.1 fixed this) |
Corrections or links lost with 6 writers in parallel | 0 of 240 |
Auto-recall trades some answers for silence and small notes; the full table, what it doesn't show, and how to run it yourself are there. Nothing here shows that it makes an AI more accurate end to end; that hasn't been tested.
It uses a small local embedding model (all-MiniLM-L6-v2). Engram indexes the assistant's replies as well as yours.
These numbers are not held-out. Engram's boosts are fixed general rules, not tuned per question, but we chose which ones to ship by watching LongMemEval and LoCoMo scores from version to version (each step is in BENCHMARKS.md), so some of the score is fitted to these two tests.
Raw meaning search alone, with none of those boosts, scores 96.8% R@5 on LongMemEval. The boosts add about two points.
One LongMemEval question is worth 0.2 points, so small differences are a question or two.
An LLM reranker (which needs an API key) can raise scores further. Engram doesn't offer one, by design.
Everything is reproducible from this repo. Full per-question-type results, earlier versions and the exact commands are in benchmarks/BENCHMARKS.md.
There are several good memory tools. Here's an honest guide.
If you want… | Use |
Memory for Claude Code or Claude Desktop that's private, free and just works | Engram |
A memory library for your own AI app, companion or agent, offline with no per-call costs | Engram |
To read and trust every line of code that touches your data | Engram |
Memory for a multi-user product in the cloud, with a dashboard and an API | A hosted service such as Mem0, Zep or Supermemory (usually needs an account, an API key and an LLM) |
Just a few standing rules ("use tabs", "my name is…") | Claude's built-in memory or a |
from engram.agents import AgentDiary
from engram.backends import get_backend
from engram.chateau import Chateau
from engram.knowledge_graph import KnowledgeGraph
from engram.searcher import Searcher
memory = Chateau() # your memory folder (~/.engram/chateau)
searcher = Searcher(get_backend("chromadb"), memory)
for hit in searcher.search("what music does Maya like", n=5):
print(hit["text"], hit["final_score"])
AgentDiary("my-assistant").write("Helped plan the week") # an agent's diary
KnowledgeGraph().add(subject="Maya", predicate="likes", obj="jazz") # facts about people and thingsThese calls are pinned by tests/test_public_api.py, so apps built on them keep working across releases. For the full default search (exact-word index included), build the backend with engram.backends.backend_from_config(engram.config.load_config()).
# Save things
engram mine ~/project --wing myapp # a folder of files
engram mine ~/Downloads/claude-export --mode convos --wing myapp # a Claude, ChatGPT or Slack export
engram watch ~/project --wing myapp # keep saving as files change
# Find things
engram search "auth decisions" --wing myapp
engram answer "What did we decide about the database?" # a written answer (needs Ollama)
engram replay --room auth-migration # a topic's history, in order
# Fix and keep things
engram correct <id> "the new, correct version" # replace an outdated memory (old one kept as history)
engram history <id> # what replaced what, when and why
engram why <id> # where it came from, what it rests on, what changed
engram forget <id> # delete a memory for good (shows what changes; add --yes)
engram export backup.json.gz # back up everything to one file
engram import backup.json.gz # restore it (checked first; safe to repeat)
# Look after it
engram status # what's in your memory
engram wake-up # the short start-of-session note
engram audit --fix # health check and safe fixesThe ID is the short code in the first column of engram search results.
engram init <dir> # guided setup
engram serve [--host H] [--port P] [--token] # local web API for apps without MCP (OpenAPI at /openapi.json)
engram reindex [--wing W] # rebuild the search index (after changing the embedding model)
engram connect <app> # add Engram to Cursor, VS Code, Gemini CLI, Codex… (no app: list)
engram install-hooks --apply # Claude Code hooks: auto-recall, auto-save, save before compacting
engram recall "a message" # preview what auto-recall would give Claude
engram setup-reranker # download the reranker model (90 MB) and turn it on
engram setup-reranker --disable # turn the reranker offengram mine <dir> # project files
engram mine <dir> --mode convos # conversation exports (Claude, ChatGPT, Slack, Claude Code)
engram mine <dir> --wing myapp --room auth # choose the wing and room
engram mine <dir> --since 2026-01-01 # skip older files
engram mine <dir> --plugin obsidian # also: notion, linear
engram watch <dir> --wing myapp # auto-save on change
engram split <dir> [--dry-run] # split concatenated transcripts
engram remember-type "Prefer SQLite for local dev" preference --wing myapp
engram remember-type --list # the 13 memory typesengram search "query" [--wing W] [--room R] [--results 20]
engram search "query" --no-decay # ignore recency
engram search "query" --no-hybrid # meaning only
engram search "query" --rerank / --no-rerank # force the reranker on or off for one search
engram answer "question" [--wing W] [--model llama3.2] [--chunks 8]engram wake-up [--wing W] [--rebuild]
engram replay --room R [--wing W] [--type decision] [--since 2026-06-01] [--min-confidence 0.8]
engram kg query "Kai" [--all]
engram kg add "Kai" works_on "Orion" --from 2025-06-01
engram kg invalidate "Kai" works_on "Orion" --ended 2026-03-01
engram kg timeline "auth-migration"
engram graph [--wing W] [--output file.png] # needs: pip install "engram-chateau[viz]"engram correct <id> "new text" [--reason "why"] # save a correction that replaces <id>
engram supersede <old-id> <new-id> [--reason R] # mark an existing memory as replacing another
engram supersede <old-id> --undo # make <old-id> current again
engram history <id> # status and full replacement history
engram correct <id> "text" --source primary --ref "cite" --based-on <evidence-id>engram forget <id> # show what deleting it would change
engram forget <id> --yes # delete it, its search entries and every link to itForgetting is for things that should never have been saved. A memory it replaced becomes current again, memories that rested on it lose that evidence (engram check lists any left with nothing behind them), and earlier exports still contain it. To change a memory without losing its history, use engram correct instead.
engram link <id> based_on <evidence-id> [--reason R] # <evidence-id> supports <id>
engram link <id> derived_from <other-id> # <id> was inferred from <other-id>
engram link <id> contradicts <other-id> # conflict, undecided
engram link <id> supersedes <old-id> # <id> replaces <old-id>
engram link <id> based_on <evidence-id> --undo # remove a link
engram source <id> user|primary|secondary|tool|inference [--ref "citation or URL"]
engram why <id> [--query "the question"] [--json] # explain a memory
engram check [--json] # what needs review; changes nothingengram export <file>[.gz] # back up everything to one file
engram import <file> [--dry-run] [--overwrite] # restore; the whole file is checked firstengram status
engram audit [--fix]
engram conflicts # resolve contradicting knowledge-graph facts
engram compress [--wing W] [--room R] # rebuild short summaries (ES)
engram provenance <drawer-id> [--history]
engram provenance --summary
engram ui # local notes app at http://127.0.0.1:7741Everything works out of the box. If you want to tweak things, settings live in ~/.engram/config.json. Every key is optional, and the defaults are the benchmarked setup.
Setting | Default | What it does |
|
| Blank out API keys, tokens and passwords ( |
|
| Local reranker; turn on with |
|
| Auto-recall in Claude Code (needs |
|
| At most this many memories per message, and how closely they must match (0 to 1) |
|
| The same bar for saved preferences, lower because a request for a choice rarely repeats the preference's words |
|
| Wings auto-recall never shows |
|
| How closely another project's memories must match to be shown |
|
| Map folders to wings when the folder name isn't what you want, e.g. |
|
| Exact-word index searched alongside meaning (SQLite, no download), built from your existing memories the first time it runs |
| unset | Use an embedding server you run (LM Studio, Ollama, llama.cpp, vLLM: anything with |
|
| Search engine: |
|
| Boost for results sharing your exact words; |
|
| Boost for memories near a time the question names; |
|
| Index a short summary of preferences and concerns mentioned in passing |
|
| Size of the key-facts part of the wake-up note |
|
| How many top results the reranker reorders |
|
| How much newer memories are favoured, and for how long |
|
| Where memories are stored |
ENGRAM_VECTOR_BACKEND=sqlitevec engram … switches the backend for one run. An embedding server works with the default chromadb backend; each server and model keeps its own index, so switching back needs no reindex and your memories are never changed. ~/.engram/identity.txt holds the short identity that starts each wake-up note.
engram: command not found after installing. pip put it somewhere not on your PATH. Use python3 -m pip install --user engram-chateau, or install with uv tool install engram-chateau / pipx install engram-chateau, which handle PATH for you.
pip: command not found. Try pip3 or python3 -m pip. Inside a uv virtual environment, use uv pip install ….
Moving to a new computer. Run engram export backup.json.gz on the old one, install Engram on the new one, then engram import backup.json.gz. Search indexes are rebuilt during the import.
Claude doesn't show the engram tools. Restart Claude Code or Claude Desktop after adding the server. If the app can't find engram-mcp, give it the full path from which engram-mcp.
"ChromaDB failed to load". ChromaDB's compiled parts don't match your Python. Try pip install --force-reinstall --no-cache-dir chromadb, or set "vector_backend": "sqlitevec", which needs no compiled parts. Then run engram mine again, because each backend keeps its own index.
Python 3.15 or newer. ChromaDB can't install there yet, so Engram falls back to sqlitevec, which matches words rather than meaning. For meaning-based search, use Python 3.11 to 3.14.
"No such command" after updating from GitHub. Run git pull origin main, then pip install -e . (or uv pip install -e .) in your Engram folder.
The search Relevance column shows <0.001. The reranker found nothing that really answers that question; try a more specific one.
A compact text form any LLM can read without a decoder. It's used only for the short context Engram loads into a model; your drawers always keep the original text. ES drops filler words, saving about 1.6× on prose and 1.1× on code.
from engram.shorthand import compress
compress("The authentication module is a critical component that has a dependency on the database.")
# → "auth module=★★ component +dep on db."Layer | Content | Size | Loaded |
L0 | Identity: who the AI is | ~50 tokens | Always |
L1 | Key facts, in shorthand | up to 120 tokens ( | Always |
L2 | The current topic's memories | On demand | When the topic comes up |
L3 | Full search | On demand | When asked |
engram ui opens a local notes app at http://127.0.0.1:7741, with a graph of linked notes, tags, pinned notes, a daily journal and Markdown editing. It keeps its notes in your browser for now, and doesn't yet show the memories in ~/.engram/; use engram search or the MCP tools for those.
File | What it does |
| Wings, rooms, halls and drawers on disk |
| Search: meaning, keywords, time, recency, reranking |
| Exact-word index (SQLite FTS5) merged with meaning search |
| Splits long text into chunks for the index |
| Understands "two weeks ago", "in June", "on May 8" |
| Spots preferences and concerns in messages |
| Optional secret redaction |
| Optional local reranker (ONNX) |
| Saving files and conversations |
| Corrections: which memories are current, which were replaced, and why |
| Evidence links, sources, |
|
|
| Checks tool arguments against each tool's schema (MCP and web) |
| Optional embedding server instead of the built-in model |
|
|
| Auto-recall hook for Claude Code |
| MCP server (31 tools), run as |
|
|
| Wake-up note and ES shorthand |
| Knowledge graph and agent diaries |
| ChromaDB (default), FAISS, sqlite-vec |
| Obsidian, Notion, Linear importers |
| Claude Code save and pre-compact hooks |
| LongMemEval and LoCoMo runners |
Python 3.9 or newer. 3.11 to 3.14 is recommended for meaning-based search.
Installed automatically: ChromaDB, typer, rich, watchdog, questionary, pyyaml and requests.
Optional extras: engram-chateau[faiss], [sqlitevec], [viz] (graph pictures) or [all].
Optional: Ollama for engram answer.
Internet use: none, apart from two one-time downloads. The embedding model (about 80 MB) downloads the first time you save or search. The optional reranker (90 MB) downloads only if you run engram setup-reranker. Your memories never leave your machine.
Bug reports, ideas and pull requests are welcome.
git clone https://github.com/TushaeBXN/engram && cd engram
pip install -e ".[dev]"
pytestEngram is published to PyPI as engram-chateau from .github/workflows/publish.yml, using PyPI trusted publishing (no stored token; owner TushaeBXN, repository engram, workflow publish.yml, environment pypi).
Bump version in pyproject.toml and __version__ in engram/__init__.py, and add a CHANGELOG.md entry.
Merge to main.
Create a new GitHub release after the merge, tagged v<version> with the dots kept (for example v1.5.1, not v1.51), targeting main. The workflow checks the tag matches the version, runs the tests, builds and uploads.
Engram's design (wings, rooms, halls, drawers and a temporal knowledge graph) is inspired by other open-source memory systems. Some retrieval ideas (the exact-word index and date understanding) are adapted from Hindsight.
MIT © 2026 Tushae Thomas
If Engram helps you remember something that mattered, a ⭐ helps other people find it.
Store a new memory drawer in the château. The result lists 'possible_updates': existing memories this one may replace. If it does, call engram_supersede (or pass 'supersedes' here).
| Name | Required | Description | Default |
|---|---|---|---|
| hall | No | facts | |
| room | No | general | |
| wing | No | default | |
| pinned | No | ||
| reason | No | Why it replaces it (used with 'supersedes') | |
| source | No | Where it came from: user (the person said it), primary (original document, law, ruling, data), secondary (reporting or analysis), tool (search or program output), inference (your own conclusion) | |
| content | Yes | Memory content to store | |
| based_on | No | IDs of memories that are evidence for this one | |
| source_ref | No | Citation, URL or document it came from | |
| supersedes | No | ID of a memory this one replaces (optional) | |
| derived_from | No | IDs of memories this one was inferred from |
Run a memory health audit. Returns JSON summary of issues found.
| Name | Required | Description | Default |
|---|---|---|---|
| fix | No | Auto-resolve safe issues. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It never discloses that passing fix=true mutates state by auto-resolving issues, nor what 'safe issues' means, whether fixes are reversible, or what permissions are required. This hides the tool's only write path.
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 short, front-loaded sentences with essentially no waste; the return-format note is mildly useful given there is no output schema. It could be slightly richer without losing concision.
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-parameter tool with no output schema, the description is minimally adequate: it names the return type (JSON summary) and the action. However, it omits what the audit covers and the mutating effect of fix=true, which an agent needs to call it safely.
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 single 'fix' parameter and its default are already fully documented in the schema. The description adds no additional meaning about the parameter's effects, so the baseline 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 states a specific verb+resource ('Run a memory health audit') and no sibling duplicates an audit function, so an agent can identify it distinctly. It stops short of naming how it differs from diagnostic siblings like engram_status or engram_replay.
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?
There is no guidance on when to run the audit, how often, or when to prefer it over engram_status. The meaning of the fix option (when to auto-resolve vs. just inspect) is never explained, leaving selection entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memory maintenance report: conclusions whose evidence was corrected or disputed, inferences with no evidence, unresolved conflicts, broken links. Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Compress text into Engram Shorthand (ES).
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| is_code | No | ||
| confidence | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full behavioral burden and discloses almost nothing: it never says whether compression is lossy or reversible, whether ES output is accepted by other tools (decompress, add_memory, etc.), or what confidence/is_code do to the result.
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?
A single front-loaded sentence with no filler, which is structurally clean. But at this length the brevity reflects under-specification rather than disciplined conciseness, so it only earns a middling score.
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 three-parameter transformation tool with no annotations, no output schema, and no parameter documentation, the description is far too thin. An agent cannot know what the compressed output looks like or whether the optional parameters matter.
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 0%, so the description must compensate and adds nothing. The 'text' input is inferable from the name, but 'is_code' and 'confidence' (integer 1-5) are completely unexplained — their effect on the compression output is unguessable.
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 (compress) and output artifact (Engram Shorthand). However, 'Engram Shorthand (ES)' is jargon that is never defined, and the description doesn't differentiate this from the sibling engram_decompress beyond the obvious inverse relationship.
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?
There is no guidance on when to compress versus storing text directly, no mention of the paired engram_decompress tool, and no stated preconditions. The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a correction: a new memory that replaces an outdated one (same wing/room/hall). The old memory stays searchable but is marked superseded, and search shows the correction first. Safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | Why it changed | |
| source | No | Where it came from: user (the person said it), primary (original document, law, ruling, data), secondary (reporting or analysis), tool (search or program output), inference (your own conclusion) | |
| content | Yes | The corrected, current information | |
| based_on | No | IDs of memories that support the corrected version | |
| memory_id | Yes | ID (or unique prefix) of the outdated memory | |
| source_ref | No | Citation, URL or document it came from |
Create a new room within a wing.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| wing | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it only says 'create'. It does not disclose whether the wing must pre-exist, whether the room name must be unique, what happens on conflict, what permissions are needed, or what the response contains. For a mutation tool this is a substantial gap.
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?
A single short, front-loaded sentence with no filler or redundancy. It is efficient, though the brevity is partly a symptom of under-specification rather than disciplined editing.
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 mutation tool with no annotations, no output schema, and 0% parameter coverage, the description is far too thin. An agent lacks the information needed to call it correctly in edge cases such as a missing wing or duplicate name.
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 0% and the description adds no meaning for any of the three parameters. It does not explain that 'wing' identifies the parent container, that 'name' is required, or that 'description' is optional free text, leaving all three undocumented.
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 (Create) and resource (room) and locates it within a wing, so an agent knows exactly what the call produces. It does not differentiate itself from the sibling engram_create_wing or clarify the wing/room hierarchy, so it falls short of a 5.
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?
No when-to-use guidance, no prerequisites (e.g. whether the wing must already exist), and no mention of alternatives such as engram_create_wing or engram_list_rooms. The agent must infer the context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new wing in the château.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Create' implies a mutation, but the description says nothing about name uniqueness, side effects on existing wings, permissions, or what happens on duplicate names — a significant gap for a write operation with zero annotation coverage.
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?
A single short, front-loaded sentence with no filler. It is appropriately sized, though its brevity here reflects under-specification rather than disciplined conciseness.
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?
With no annotations, no output schema, 0% parameter coverage, and an unexplained domain metaphor among many related siblings, the description leaves essential information missing: what a wing is, how it relates to rooms, and what a caller gets back.
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 0%, so the description must compensate and does not. The required 'name' parameter is only weakly implied by the sentence, and the optional 'description' parameter is not mentioned at all.
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?
It gives a specific verb and resource ('Create a new wing'), so the basic action is unambiguous. However, 'wing in the château' is unexplained domain metaphor, and nothing distinguishes it from the sibling engram_create_room or clarifies the wing/room hierarchy an agent must understand to use it correctly.
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?
There is no guidance on when to create a wing versus a room (engram_create_room), no stated prerequisites, and no mention of whether wings are containers for rooms. The agent must infer usage entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decompress Engram Shorthand (ES) back to natural language.
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It doesn't state that this is a stateless/non-mutating transform, nor what happens on malformed or non-ES input, nor any size limits — all of which matter for an inverse-decoding tool.
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?
A single tight sentence with the verb and resource front-loaded; nothing superfluous.
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-parameter tool with no annotations or output schema, it does state the output type (natural language), but failure modes, input validity requirements, and its relationship to engram_compress are 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 0% and the single 'text' parameter is undocumented. The description's reference to 'ES' implies the input should be Engram Shorthand, but it never ties that to the parameter or describes acceptable formats, so it only partially compensates.
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?
Names a specific verb ('Decompress') and a specific resource ('Engram Shorthand (ES)'), and clarifies the output form ('back to natural language'). It doesn't explicitly cite the inverse sibling engram_compress, but the phrasing makes the inverse relationship inferable.
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?
No statement of when to use this instead of engram_compress or any other sibling, and no preconditions (e.g., that the input must be valid ES). Usage is only implied by the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a drawer from the château.
| Name | Required | Description | Default |
|---|---|---|---|
| hall | Yes | ||
| room | Yes | ||
| wing | Yes | ||
| drawer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Delete' implies a destructive mutation, but the description says nothing about irreversibility, whether child memories are removed, required permissions, or side effects on wings/rooms/halls. For a destructive tool with zero annotation coverage this is a substantial disclosure gap.
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?
It is a single front-loaded sentence with no filler, which is structurally clean. However, the brevity reflects under-specification rather than efficient communication, since essential addressing and impact information is omitted.
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 destructive four-parameter tool with no annotations and no output schema, the description omits addressing semantics, consequences of deletion, and confirmation requirements. It is not misleading, but it is far from sufficient for an agent to invoke the tool safely.
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 0% across four required parameters, and the description mentions none of them. It never explains the wing/room/hall/drawer_id addressing hierarchy or whether these are names or IDs, leaving the agent with no guidance for supplying a valid path.
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 specific verb (delete) and resource (drawer), so an agent knows the operation is a removal targeted at a drawer entity. It does not, however, differentiate from siblings that also remove or modify drawers (engram_supersede, engram_dispute, engram_correct), and the domain metaphor (château) adds flavor rather than precision.
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?
There is no statement of when to use this tool versus engram_supersede, engram_correct, engram_dispute, or engram_get_drawer, and no prerequisites or exclusions. An agent must guess whether deletion is the right remedy for stale content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent diary entries for a specialist agent.
| Name | Required | Description | Default |
|---|---|---|---|
| agent | Yes | ||
| last_n | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden. It implies a safe, non-mutating read and adds a recency notion via 'recent', but says nothing about ordering, pagination, permissions, or behavior when the agent has no entries.
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?
A single front-loaded sentence with no filler or redundancy. It is efficiently sized, though the brevity comes at the cost of the specification gaps noted elsewhere.
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?
No annotations, no output schema, and 0% parameter coverage mean the description is the only documentation, yet it omits record ordering, the meaning of last_n, and return shape. For a two-parameter retrieval tool this leaves meaningful gaps for an agent to guess at.
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 0% and the description never names or explains either parameter. The phrase 'for a specialist agent' loosely maps to the required 'agent' parameter, but 'last_n' and its default of 10 are left entirely undefined in both schema and prose.
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 (Read) and resource (recent diary entries) scoped to a specialist agent, which cleanly separates it from the engram_diary_write sibling. It does not explicitly name or rule out the other retrieval siblings, so it stops short of a 5.
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?
The description gives no when-to-use guidance, no prerequisites, and does not mention alternatives such as engram_search, engram_history, or engram_get_drawer, which could plausibly retrieve overlapping content. Usage is only implied by the verb 'Read'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a diary entry for a specialist agent.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | ||
| agent | Yes | ||
| entry | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure, and it says almost nothing. It does not state whether entries persist, whether writes are append-only or overwrite existing entries, what permissions are needed, or what the response contains for a mutation tool.
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?
It is a single front-loaded sentence with zero padding, which is structurally clean. However, the brevity reads as under-specification rather than disciplined conciseness for a mutation tool in a multi-tool memory system.
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?
Given a write operation, three undocumented parameters, no annotations, and no output schema, the description should do far more work. It leaves the agent without enough context to invoke the tool confidently or to predict its effect.
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 0% for all three parameters, so the description must compensate and does not. 'Agent' and 'entry' are loosely inferable from the wording, but 'tags' is entirely unexplained and no format, length, or content expectations are given.
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 ('Write a diary entry') plus a scope qualifier ('for a specialist agent'), so the agent knows what operation is being performed. It does not, however, distinguish this from the sibling engram_diary_read or explain what a 'diary entry' represents in this memory system.
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?
There is no guidance on when to write a diary entry versus other memory tools such as engram_add_memory, engram_pin, or engram_kg_add, nor any prerequisites or exclusions. 'For a specialist agent' hints at scope but does not tell the agent when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark two memories as conflicting when it is not yet clear which is right.
| Name | Required | Description | Default |
|---|---|---|---|
| id_a | Yes | ||
| id_b | Yes | ||
| reason | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It says 'Mark' but never discloses whether this mutates stored state, whether the marking is reversible, what permissions are needed, or what a later resolution requires. For a state-changing memory operation this is a significant gap.
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?
A single front-loaded sentence with no filler; the purpose and its qualifying condition arrive immediately. It is efficient, though its brevity contributes to the disclosure gaps elsewhere.
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?
With no annotations, no output schema, and 0% parameter coverage, the description leaves too much open for a tool that alters memory relationships. Missing are what a dispute does to the two memories, the effect on retrieval/search, and how the conflict is later resolved.
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 0%, so the description must compensate and largely does not. 'Two memories' loosely maps to id_a and id_b, but the required memory identifier format is never stated and the optional 'reason' parameter is entirely unexplained.
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 ('Mark') and resource ('two memories') with an outcome ('as conflicting'). It does not name or distinguish itself from closely related siblings like engram_correct or engram_supersede, so an agent must infer the boundary itself.
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?
The clause 'when it is not yet clear which is right' gives an implied condition for use, distinguishing it loosely from resolution tools. However, it never names an alternative (engram_correct, engram_supersede) or states when NOT to dispute, leaving the routing decision to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a specific drawer by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| hall | No | ||
| room | No | ||
| wing | No | ||
| drawer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not confirm the operation is read-only, say what happens if the drawer_id is not found, mention required permissions, or describe the relationship between drawer_id and the hall/room/wing parameters. Only the verb 'fetch' hints at a safe 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?
The description is a single short, front-loaded sentence with no filler and no wasted clauses. It is appropriately sized for the amount of information it conveys, though that information is thin.
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 4-parameter tool with zero annotation coverage, no parameter documentation, and no output schema, the description is far too sparse. An agent lacks the hierarchical semantics of hall/room/wing, the failure behavior for missing drawers, and any routing guidance relative to the many sibling retrieval tools.
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 0% across 4 parameters, so the description must compensate and largely fails. 'By ID' only gestures at drawer_id (the sole required field) and gives no meaning, format, or source for hall, room, or wing, which are presumably hierarchical locators and undocumented in both the schema and description.
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 verb ('Fetch') and resource ('a specific drawer by ID'), which is clear. However, it does nothing to differentiate this retrieval tool from siblings like engram_search, engram_load_room, or engram_history, so an agent cannot tell from the text alone why it would pick this one.
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?
There is no when-to-use guidance at all: no mention of when to prefer this over engram_search, engram_load_room, or engram_history, and no note about prerequisites or the hierarchical scope (hall/room/wing) the caller may need. The agent is left to infer usage entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A memory's status (current, superseded or disputed), what replaced it, what it replaced, when and why.
| Name | Required | Description | Default |
|---|---|---|---|
| memory_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose the expected return content — status categories (current, superseded, disputed), lineage, and the when/why of replacement — which is genuinely useful since no output schema exists. It says nothing about read-only nature, permissions, or failure modes, so it is partial rather than complete.
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 single sentence is compact and wastes no words, but it is a fragment rather than a front-loaded action statement, so the most important information (that this is a lookup/retrieval operation) is only implied.
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-parameter read tool with no annotations and no output schema, the description covers the return content reasonably well but omits read-only assurance, the parameter's nature, and any sibling disambiguation. It is minimally viable rather than complete given the crowded namespace.
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 0% on a single required parameter, memory_id, whose format and meaning are never described. The phrase 'a memory's status' implies the tool operates on one identified memory, which is enough for an agent to map the parameter, but no syntax or ID-format detail compensates for the empty schema.
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 the resource and its facets (a memory's status, lineage, timing, reason), so the agent can infer it retrieves version-history information. However it is a noun-phrase fragment with no verb, and it never distinguishes this from siblings such as engram_replay, engram_audit, or engram_get_drawer, so the exact action is left to inference.
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?
There is no when-to-use guidance, no stated preconditions, and no mention of any alternative tool. In a toolset crowded with overlapping memory-inspection siblings (engram_replay, engram_audit, engram_get_drawer), the absence of routing guidance is a real gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a triple to the knowledge graph.
| Name | Required | Description | Default |
|---|---|---|---|
| object | Yes | ||
| subject | Yes | ||
| predicate | Yes | ||
| confidence | No | ||
| valid_from | No | ||
| valid_until | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It says nothing about permissions, idempotency, validation, side effects, or how the graph is modified—only that a triple is added.
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 single sentence is concise and front-loaded, but it is under-specified for a 6-parameter mutation tool. It is too terse to be considered appropriately sized given the complexity.
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?
With no annotations, no output schema, and six undocumented parameters, the description is completely inadequate for an agent to invoke the tool correctly. It omits required context about behavior, parameters, and usage.
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?
The schema has 6 parameters with 0% description coverage, and the description does not mention any of them. It fails to explain subject, predicate, object, or the optional confidence, valid_from, and valid_until fields.
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 clear verb ('Add') and resource ('triple to the knowledge graph'). It distinguishes the operation from read-only siblings like engram_kg_query, but does not explicitly differentiate from other mutation tools such as engram_kg_invalidate or engram_correct.
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?
Provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, context, or sibling tools like engram_kg_query or engram_kg_invalidate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invalidate (end) a KG triple.
| Name | Required | Description | Default |
|---|---|---|---|
| ended | No | ||
| object | Yes | ||
| subject | Yes | ||
| predicate | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. The word 'end' implies the triple is marked invalid rather than physically deleted, which is mildly useful, but it does not say whether the operation is reversible, whether subject/predicate/object must already exist, or what conflict/not-found behavior looks like.
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 single sentence is short but under-specified rather than truly concise; there is no front-loaded context about effect or scope, just a restatement of the name.
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 4-parameter mutation tool with zero annotation coverage, zero schema descriptions, and no output schema, the description is far too thin. An agent cannot determine parameter meanings, side effects, or error conditions from what is provided.
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 0% across 4 parameters, and the description explains none of them. The purpose of 'ended' (a string, likely a timestamp or flag) is particularly opaque and undocumented anywhere.
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 verb ('Invalidate') and resource ('KG triple'), and the parenthetical '(end)' hints at temporal rather than hard deletion. However, it gives no differentiation from closely related siblings like engram_kg_add, engram_supersede, or engram_dispute, so an agent must infer which mutation is appropriate.
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?
There is no guidance on when to use this tool versus engram_supersede, engram_dispute, engram_kg_add, or engram_correct, all of which presumably operate on KG facts. No prerequisites or preconditions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the temporal knowledge graph for an entity.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes | ||
| predicate | No | ||
| active_only | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says nothing about whether the query returns only current facts versus historical/superseded ones, how the temporal aspect is surfaced, or how results are ordered or paginated.
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?
A single front-loaded sentence with no padding, which is structurally efficient. However, it is under-specified rather than genuinely concise, leaving room for detail it omits.
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?
With no annotations, no output schema, and three parameters at 0% schema coverage, the definition is too thin for the tool's complexity. It omits return shape and the temporal/active-fact semantics an agent would need to call it correctly.
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 0%, so the description must compensate but only covers the 'entity' parameter implicitly. The 'predicate' filter and especially 'active_only' (default true, implying inclusion of invalidated/superseded facts when false) are left entirely unexplained.
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 (Query) and resource (temporal knowledge graph) scoped to an entity, which is clearer than a bare name restatement. It does not explicitly distinguish itself from the KG siblings (engram_kg_add, engram_kg_invalidate, engram_kg_timeline), though the read-oriented verb implicitly separates it.
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?
No guidance on when to prefer this over engram_kg_timeline or engram_search, and no mention of prerequisites or exclusions. The agent must infer usage purely from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return chronological timeline of all triples for an entity.
| Name | Required | Description | Default |
|---|---|---|---|
| entity | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implicitly discloses a read-only nature and a chronological ordering, but says nothing about permissions, pagination, result size limits, or what happens for an entity with no triples. Useful context, yet a notable gap for a tool with zero annotation coverage.
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?
One short, front-loaded sentence with no redundant or wasted wording — exactly the right size for the information it conveys.
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 single-parameter read tool with no output schema, the minimum is arguably met, but the description does not describe the return shape (triple format, timestamp fields, ordering direction) that an agent would need to interpret the 'chronological timeline' it promises.
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 0% and there is a single required 'entity' parameter, so the description must compensate but adds almost nothing beyond the phrase 'for an entity'. Since the lone parameter is an obvious identifier and its meaning ('the entity whose triples are returned') is inferable, a 3 is fair, but no format or matching details are given.
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 ('Return') and resource ('chronological timeline of all triples for an entity'), which is clearly distinguishable from kg_query (point query) and kg_add/invalidate (mutations). However, it never explicitly contrasts itself with the nearest sibling, engram_kg_query, so it stops short of a 5.
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?
The description gives no when-to-use guidance, no exclusions, and does not mention alternatives such as engram_kg_query or engram_history. An agent has to infer from the name alone when a timeline view is preferable to a query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record how two stored memories relate: 'memory_id target_id'. based_on: target is evidence for memory. derived_from: memory was inferred from target. contradicts: they conflict, undecided. supersedes: memory replaces target. undo=true removes the link. Safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| undo | No | ||
| reason | No | ||
| relation | Yes | ||
| memory_id | Yes | ||
| target_id | Yes |
List all rooms in a wing.
| Name | Required | Description | Default |
|---|---|---|---|
| wing | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'List all' implies a read-only enumeration, but nothing is said about permissions, whether rooms are filtered, pagination, or the shape of results.
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?
A single front-loaded sentence with no filler, appropriate for a one-parameter list tool. It is lean rather than padded, though the brevity shades into under-specification elsewhere.
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 simple read tool with no output schema, the description covers the minimum: action, resource, and scoping parameter. It leaves the agent without the return format or how to obtain a wing, which are needed to call it confidently.
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 0% for the single required 'wing' parameter. The description only repeats the schema's own key name and adds no information about wing identity format, valid values, or how to discover a wing.
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 clear verb (list) and resource (rooms) with scope (in a wing), so an agent knows it enumerates rooms. It does not differentiate itself from plausible siblings such as engram_list_wings or engram_get_drawer, so it stops short of a 5.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternative tools. An agent must infer that this is the discovery step before engram_load_room or engram_get_drawer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all wings in the château.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'List' implies read-only operation, but the description does not explicitly disclose safety, permissions, side effects, pagination, or return characteristics, which are needed for full transparency.
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?
A single short sentence that is front-loaded and waste-free. For a zero-argument list operation, this is appropriately sized and structured.
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?
Given the zero-parameter schema and no output schema, the description is minimally adequate to invoke the tool. However, it does not explain the return format, the domain concept of a 'wing', or its relationship to sibling list tools, leaving some contextual gaps.
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?
The tool has zero parameters, so the baseline is 4 by rule. The empty schema and 100% description coverage mean there is no additional parameter semantics to convey.
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 'List' and resource 'wings' with the scope 'all', making the basic operation clear. However, it does not differentiate from sibling tools like engram_list_rooms or engram_create_wing, so it stops short of full sibling-aware clarity.
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?
No when-to-use guidance, prerequisites, or alternatives are provided. The description only states what the tool does, leaving the agent to infer that this is the wing-level list versus the room-level list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return L2 context for a specific room (ES-compressed closets for all halls).
| Name | Required | Description | Default |
|---|---|---|---|
| room | Yes | ||
| wing | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. The verb 'load' leaves open whether this operation mutates state, decompresses data, requires an existing room, or fails for missing rooms, and the parenthetical about 'ES-compressed closets' implies decompression behavior without confirming it.
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?
A single short sentence with no padding and the core intent front-loaded; its flaw is under-specification rather than verbosity. The trailing parenthetical, however, spends words on jargon that adds no usable 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?
With no annotations, no output schema, and 0% parameter coverage, the description is the only source of behavioral and input context — and it leaves both the 'wing' parameter and the read/mutate semantics unexplained. For a two-required-parameter tool in a dense sibling cluster, this is inadequate.
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 0% and neither parameter is described in the schema. The description alludes only to 'a specific room' and says nothing about the required 'wing' parameter or how room/wing interact, leaving half the required input undocumented anywhere.
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 supplies a verb and resource ('Return L2 context for a specific room'), but the domain jargon ('L2 context', 'ES-compressed closets for all halls') is unexplained and the parenthetical obscures rather than clarifies scope. It also does not distinguish itself from close siblings like engram_get_drawer or engram_list_rooms, so an agent cannot confidently route between them.
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?
There is no guidance on when to call this versus alternatives such as engram_get_drawer, engram_list_rooms, or engram_decompress — all plausibly overlapping. No prerequisites, no preconditions, no exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pin a drawer so it bypasses recency decay.
| Name | Required | Description | Default |
|---|---|---|---|
| drawer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it does disclose the key behavioral effect: pinning bypasses recency decay. It does not state reversibility (unpin), persistence across sessions, idempotency, or permission requirements, leaving meaningful gaps for a mutation-style operation.
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?
One short sentence, front-loaded with the verb and the payoff condition. No filler or redundancy.
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 simple one-parameter tool this covers the core operation, but with no annotations and no output schema it omits reversibility, return behavior, and any interaction with related tools like engram_get_drawer or decay-related siblings.
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 0% and the single drawer_id parameter is undocumented in the schema. The description implies a drawer identifier is required but adds no format, source, or constraints beyond what the parameter name already suggests.
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 (pin) plus resource (drawer) and the effect (bypasses recency decay), which is more than a restatement of the name. It doesn't explicitly distinguish itself from siblings like engram_get_drawer or engram_delete_drawer, but the 'pin' verb is unambiguous.
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?
No guidance on when to pin a drawer versus alternatives such as engram_search or engram_get_drawer, no prerequisites, and no note on whether/how to unpin. The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The few memories clearly relevant to a message, current versions first, or a note that nothing matched. Call it before answering anything that may depend on past work, decisions or preferences.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Project folder, if known (its memories come first) | |
| message | Yes | The user's message or the task at hand |
Return the chronological story of a room (session replay).
| Name | Required | Description | Default |
|---|---|---|---|
| room | Yes | ||
| wing | No | ||
| limit | No | ||
| format | No | text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses almost nothing beyond the read implication of "Return." It does not state whether results are paginated/truncated (relevant given a limit param), how the format enum affects output, or whether replay is scoped by wing or compresses/merges events.
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?
A single front-loaded sentence with no filler; the core action leads. It is efficient, though its brevity is closer to under-specification than disciplined concision.
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 4-parameter tool with zero annotation coverage and no output schema, one sentence is not enough. The agent lacks the information needed to choose among the temporal/history siblings or to predict how limit and format shape the returned replay.
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 0% across 4 parameters, so the description must compensate but does not. "room" and "chronological" loosely map to the room param and ordering, but wing, limit (default 50), and the text/json format enum are never explained in either place.
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 has a verb ("Return") and a resource ("the chronological story of a room"), with "session replay" as a clarifying gloss. However, "story of a room" is fuzzy, and it gives no signal distinguishing it from siblings like engram_history, engram_diary_read, or engram_load_room, so the agent cannot route confidently.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives despite the presence of closely related siblings (engram_history, engram_diary_read, engram_kg_timeline). The invocation context is entirely left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search across the château. Returns ranked results with recency weighting.
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| room | No | ||
| wing | No | ||
| query | Yes | Search query | |
| no_decay | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, this text must carry the full behavioral burden. It usefully discloses that results are ranked and recency-weighted, which hints at the no_decay parameter's effect, but says nothing about read-only safety, result limits, pagination, or whether searches span all rooms/wings by default.
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 short sentences, front-loaded with the core action and free of padding. If anything it is under-specified rather than verbose, so brevity here is not a virtue the description fully earns.
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?
A five-parameter search tool with no annotations, no output schema, and 20% schema coverage needs the description to explain scoping (room/wing), result count (n), and decay behavior. It covers only the last of these obliquely, leaving the agent guessing about invocation semantics.
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 only 20% — just `query` is documented — and the description adds no meaning for `n`, `room`, `wing`, or `no_decay`. The single mention of 'recency weighting' indirectly explains what no_decay toggles, but that is thin compensation for four undocumented parameters.
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?
Identifies a verb (semantic search) and a resource (the château), so the basic operation is clear. However, 'château' is unexplained jargon and the description does not distinguish this from siblings like engram_kg_query or engram_history, which also retrieve stored knowledge.
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?
There is no when-to-use guidance, no mention of alternatives (e.g., kg_query for structured lookups vs. this for fuzzy recall), and no prerequisites or exclusions. The agent must infer the use case entirely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record where a stored memory came from (and optionally the citation or URL).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Where it came from: user (the person said it), primary (original document, law, ruling, data), secondary (reporting or analysis), tool (search or program output), inference (your own conclusion) | |
| memory_id | Yes | ||
| source_ref | No | Citation, URL or document it came from |
Return château statistics (wings, rooms, drawers, closets).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. 'Return' implies a read-only, non-destructive call and the enumerated items describe the shape of the returned counts, which is useful, but it omits scope (whole château vs. a single wing/room) and never states explicitly that nothing is mutated.
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?
One short sentence, front-loaded with the verb and resource, with no filler. Every element (statistics, and the four counted categories) earns its place.
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?
No output schema exists, so the description must hint at the return value, and it does by naming the four counted categories. It stops short of stating format or whether counts are scoped/global, which is the only remaining gap for a zero-arg status tool.
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?
The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The parenthetical enumeration of countable entities is a small bonus that clarifies what the statistics cover.
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 ('Return') plus resource ('château statistics') and enumerates the counted entities (wings, rooms, drawers, closets), so the agent knows this is an aggregate counts tool. It does not, however, differentiate itself from near-neighbours like engram_audit, engram_list_wings, or engram_list_rooms, which a reader could easily confuse with it.
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?
There is no when-to-use guidance, no prerequisites, and no mention of when to prefer this over engram_audit or the list_* tools. The only cue is the word 'statistics', leaving the agent to infer that this is a cheap overview call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that one stored memory replaces another (e.g. 'we moved to PostgreSQL' replaces 'we use SQLite'). Set undo=true to make the old memory current again. Safe to retry.
| Name | Required | Description | Default |
|---|---|---|---|
| undo | No | ||
| new_id | No | ID of the memory that replaces it | |
| old_id | Yes | ID of the outdated memory | |
| reason | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses idempotency ('Safe to retry') and the undo semantics, but omits whether this is destructive, what happens to the new memory, and any permission requirements.
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 short sentences, front-loaded with the core purpose and a clarifying example, with no filler. It is appropriately sized for a four-parameter mutation.
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?
There is no output schema and no annotations, so the description must carry everything. It covers the core action, undo, and retry safety, but leaves the reason parameter and mutation side effects (what the superseded memory becomes) unaddressed.
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 50%: new_id and old_id are documented by the schema, and the description adds real meaning for undo ('make the old memory current again'). But 'reason' has no description in either place, leaving one parameter fully unexplained.
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 concrete verb+resource: 'Record that one stored memory replaces another', fleshed out with a worked example ('we moved to PostgreSQL' replaces 'we use SQLite'). This clearly separates it from read/query siblings, though it never names the nearest alternatives (engram_correct, engram_dispute, engram_kg_invalidate), so the agent must infer the boundary.
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?
Usage is implied through the example scenario, and the undo sentence clarifies the reverse operation. However there is no explicit when-not guidance and no routing to sibling tools such as engram_correct or engram_dispute, which an agent could plausibly confuse with this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return L0+L1 cold-start context (~170 tokens). Load this at the start of every session.
| Name | Required | Description | Default |
|---|---|---|---|
| wing | No | ||
| rebuild_l1 | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It usefully discloses the payload size (~170 tokens) and that this is a cold-start/boot operation, but it is silent on whether the call mutates stored state, which matters because the rebuild_l1 parameter implies a possible write side effect, and it says nothing about auth or idempotency.
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 sentences, no filler, with the return payload stated first and the usage directive second. Every clause earns its place.
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?
No annotations, no output schema, and 0% parameter coverage leave the definition thin: the agent knows roughly what comes back but not what the two inputs change. For a boot tool whose rebuild_l1 flag can alter behavior, the description should explain that flag and the return shape.
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 0% and neither parameter is mentioned in the description. The agent gets no explanation of what 'wing' scopes or what forcing rebuild_l1 does (presumably an expensive L1 regeneration), which is a meaningful gap for a 2-parameter tool.
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 concrete verb (Return) and a concrete resource (L0+L1 cold-start context) and scopes it as the session-start payload, which differentiates it from siblings like engram_load_room or engram_search. The 'L0+L1' shorthand is internal jargon an agent cannot decode from the definition alone, which keeps it out of 5 territory.
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?
"Load this at the start of every session" is an explicit, unambiguous when-to-use directive, stronger than typical implied guidance. It does not, however, mention any alternative or when NOT to call it (e.g., whether it is redundant after engram_status).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain a memory: where it came from, when, whether it is record or inference, the evidence it rests on (and whether that evidence was since corrected or disputed), earlier versions and their evidence, conflicts, and, given the query, why search ranked it. Use it before relying on a conclusion or when asked to justify one.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The question it was retrieved for (optional) | |
| memory_id | Yes |
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.10.5engram_add_memory4 fields changedInput schema / properties / based_onAdded value: +{
+ "description": "IDs of memories that are evidence for this one",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / derived_fromAdded value: +{
+ "description": "IDs of memories this one was inferred from",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / sourceAdded value: +{
+ "description": "Where it came from: user (the person said it), primary (original document, law, ruling, data), secondary (reporting or analysis), tool (search or program output), inference (your own conclusion)",
+ "enum": [
+ "user",
+ "primary",
+ "secondary",
+ "tool",
+ "inference"
+ ],
+ "type": "string"
+}Input schema / properties / source_refAdded value: +{
+ "description": "Citation, URL or document it came from",
+ "type": "string"
+}engram_checkengram_correct3 fields changedInput schema / properties / based_onAdded value: +{
+ "description": "IDs of memories that support the corrected version",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / sourceAdded value: +{
+ "description": "Where it came from: user (the person said it), primary (original document, law, ruling, data), secondary (reporting or analysis), tool (search or program output), inference (your own conclusion)",
+ "enum": [
+ "user",
+ "primary",
+ "secondary",
+ "tool",
+ "inference"
+ ],
+ "type": "string"
+}Input schema / properties / source_refAdded value: +{
+ "description": "Citation, URL or document it came from",
+ "type": "string"
+}engram_linkengram_recallengram_sourceengram_whyv1.7.0engram_add_memoryengram_auditengram_compressengram_correctengram_create_roomengram_create_wingengram_decompressengram_delete_drawerengram_diary_readengram_diary_writeengram_disputeengram_get_drawerengram_historyengram_kg_addengram_kg_invalidateengram_kg_queryengram_kg_timelineengram_list_roomsengram_list_wingsengram_load_roomengram_pinengram_replayengram_searchengram_statusengram_supersedeengram_wake_upScored across 26 tools
Most tools target distinct resources or actions, but engram_add_memory, engram_supersede, and engram_correct overlap heavily—add_memory even references possible updates, and correct vs supersede both describe replacing an outdated memory with a new one. Context-loading tools (wake_up, load_room, replay) are distinguishable but close in scope.
All tools share the engram_ prefix and snake_case, with a coherent kg_ sub-namespace for graph operations. Names mix single verbs (search, status, audit) with verb_noun forms (create_room, list_wings) but stay readable and predictable overall.
At 26 tools the surface is on the heavy side for a memory system, though the domain (memory CRUD, KG, diary, compression, lifecycle/pinning) genuinely spans several sub-areas. It sits just past the 25-tool mark where density starts to weigh on selection.
Coverage is broad: room/wing creation, drawer add/get/delete, supersede/correct/dispute/history lifecycle, full KG add/query/invalidate/timeline, diary read/write, and compression. Gaps are minor—no delete for wings/rooms and no explicit drawer update, but corrections largely cover mutation.
Cross-tool persistent memory and context for AI assistants over MCP.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
Persistent memory for AI agents across Claude, ChatGPT and any MCP client.
