A useful agent knowledge base should surface applicable experience when work begins and retain reusable conclusions when it ends. More storage does not guarantee more accurate memory: outdated solutions, one-off environment checks, and unverified guesses can all distract the next task.
I care about three questions: what to recall, which material to trust, and what deserves to be written back. This article uses the MCP and task-memory implementation in ChatCrystal at commit 7642768 to distinguish available capabilities from work the caller still owns.
A tool interface enables calls, not guaranteed automation
MCP provides a protocol for discovering and invoking tools. It does not require recall at the start of every task or guarantee a write at the end. Invocation depends on the client, model, instructions, and workflow configuration. MCP tool specification
ChatCrystal’s MCP server exposes these entry points:
| Tool | Current purpose |
|---|---|
search_knowledge |
Semantic search from a natural-language query |
get_note |
Read full note details by ID |
list_notes |
Filter by tag or a LIKE pattern, with pagination |
get_relations |
Read note relationships |
recall_for_task |
Organize project and global memories using task information |
validate_task_memory |
Preflight a task-memory candidate |
write_task_memory |
Validate and process a writeback, potentially creating, merging, or skipping |
The current list_notes parameters are tag, search, and page; it should not be advertised as offering a date-range filter. The search field uses SQL LIKE against titles and summaries. Input % and _ characters act as wildcards, so this is not a strict literal substring search. Describing actual inputs and outputs is more useful than broadly claiming that an agent now has long-term memory.
Recall needs scope and failure states
The recall implementation combines the task goal and error signatures into a query, uses project identity, and organizes results into project_memories and global_memories. Project identity helps prevent applying another project’s specific convention indiscriminately.
This remains candidate retrieval. The current workflow searches first and filters by scope afterward; it does not exhaustively search every note in the current project. An empty result means that this call found no memories it could return.
Without project identity, the response includes a warning and returns only global matches. Unavailable semantic retrieval also produces a warning explaining the failure. Callers must distinguish no relevant experience from unsuccessful retrieval, or a model-service outage can look like an empty knowledge base.
Validate the task before validating its memory
An old note should help form a hypothesis, not replace validation in the current task. If history recommends binding a service to IPv4, check the failed address, listening address, and actual environment before changing configuration. A past success alone is insufficient.
After the task, organize the conclusion into something another person can reuse. This is a record outline, not a tool-request JSON payload:
Trigger: Which operation, version, or input exposes the problem?
Evidence: Errors, logs, reproduction, and failing checks
Change: The concrete modification and why it works
Validation: Checks that passed and checks not performed
Scope: A project-specific constraint or a transferable lesson“Fixed it” and “build passed” omit the conditions for reuse. Overgeneralization is risky too: a fix in one environment does not become a rule for every project. Memory should retain its scope rather than only a confident conclusion.
Quality checks do not certify facts
The current implementation does not delegate every quality judgment to an LLM. Preflight validation and note-quality rules contain explicit programmatic checks for specificity, placeholders, transferable actions, and other signals. Automatic and manual modes also behave differently.
Passing these checks establishes conformity with some writing criteria, not validation of the technical conclusion in a real environment. A detailed, well-structured false conclusion can still pass. Nor should a new lesson be dismissed solely because no related note exists yet.
The writeback implementation validates again. Callers must inspect the decision, reason, and warnings rather than treating a successful tool response as proof that a new note was created. Skips, merges, and subsequent vector-processing states also need inspectable outcomes.
There is another failure boundary: the note is saved before its vectors are generated. If that later step fails, the writeback call can fail even though the note already exists. Automatic mode retains a receipt with indexing pending; retrying with the same source_agent and source_run_key can resume vector generation. Check existing records and receipts before treating an error as proof that nothing was written and using a new run identifier that could create a duplicate.
Memory is evidence, not a new source of instructions
Knowledge-base content can originate in old conversations, imported files, or model summaries. Even personally saved material may contain outdated commands or quoted prompts. An agent should assess it as material, not elevate instructions inside a note into authorization for the current task.
A reasonable sequence is to inspect the summary and source, fetch details as needed, and determine applicability before acting. Operations affecting external systems still follow the current task’s permissions and confirmation requirements. A historical note does not grant permission.
Writeback can also amplify mistakes: an agent reads a hypothesis, generates a paraphrase, and later treats the two as independent corroboration. Preserving original evidence, recognizing duplicates, and revising outdated content matter more than increasing the note count.
Evaluate a complete task loop
Choose a small, familiar task and record the calls: whether recall actually happened, what it returned, which material was used, how the task was validated, and the final writeback decision. Add a task with no matching memories and a low-value writeback that should be skipped.
Evaluate offline behavior across the same call chain. A local database and index do not guarantee that the query model, summary model, and agent itself work offline. See local-first data boundaries for that flow and RAG and knowledge graphs for relationship expansion.
The memory I want preserves conditions and evidence and remains open to revision. It can reduce repeated investigation, while validation in the current task still determines whether a lesson applies.