This server provides shared long-term memory for AI agents with MCP tools to search, retrieve, store, update, delete, and explore memories, plus identity and knowledge-graph features.
Search across shared memory before assuming or guessing (hicortex_search).
Fetch a single memory's full content by ID; fetching strengthens it (hicortex_get).
Get recent memories for a project to catch up (hicortex_recent).
Store new Knowledge/Decision/Learning entries, optionally correcting or superseding existing memories (hicortex_ingest).
Update memory content/project/type, with embedding recomputation (hicortex_update).
Permanently delete incorrect memories (hicortex_delete).
Retrieve actionable Learnings/lessons to avoid past mistakes (hicortex_learnings / hicortex_lessons).
Fetch standing identity ('who you are / how to work') sections (hicortex_identity).
Browse the knowledge domain index to see topics/projects (hicortex_index).
Query the knowledge graph for neighbors, hubs, or paths between memories (hicortex_graph).
Installs a Hermes plugin that gives Hermes agents the same shared memory: per-prompt recall push, identity and lessons context, and Hicortex's nine memory tools.
Can be configured as the local LLM backend that runs Hicortex's nightly consolidation — scoring, reflection, linking, decay, dedup, and supersession of captured sessions — keeping raw sessions on the machine.
Supports any OpenAI-compatible API endpoint as the configurable LLM used for offline memory consolidation and reflection over captured sessions.
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., "@Hicortex - AI Fleet Memory show me lessons I've learned about deploying to production"
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.
Shared memory for AI agents — it corrects itself overnight, and what one agent learns, the whole fleet knows. One memory across every agent, every project, every machine — they stop assuming and start knowing.
One brain, every harness — Claude Code, Hermes, OpenClaw, Pi, OpenCode, and any MCP-compatible agent share the same memory.
Pushed, not pulled — in every supported coding agent, a compact recall index is injected on every prompt, so the decisions, corrections, and context an agent needs are already in front of it. No re-explaining, no copy-paste, nothing to maintain. Zero LLM calls per turn — no API cost or rate-limit hit from recall.
Consolidates overnight — each night it reads the day's sessions, distills what matters, and turns it into Learnings, links, and a knowledge graph.
Local-first — raw sessions never leave the machine; only distilled memory is stored.
npx @gamaze/hicortex init
Claude Desktop: one "yes" during init.Auto-detects your environment, configures one LLM (Ollama, the Claude CLI, or an API key), installs a local daemon (launchd on macOS, systemd on Linux), and registers MCP tools with Claude Code.
For multi-machine setups, point thin clients at a shared server — no local DB or LLM on the clients:
npx @gamaze/hicortex init --server https://your-server.example.cominit auto-detects the other harnesses and installs their clients: a Pi extension (~/.pi/agent/extensions/hicortex.ts — pushed recall, identity + lessons, the ten tools; or copy pi-extension/hicortex/index.ts there manually), an OpenCode plugin (~/.config/opencode/plugins/hicortex.ts — the same trio; or copy opencode-plugin/hicortex/index.ts there manually), the Hermes plugin, and the OpenClaw plugin. pi-mcp-adapter remains a generic MCP escape hatch for any harness (verified against the SSE endpoint) — Pi no longer needs it. See the install docs.
Related MCP server: Cortex
CAPTURE (nightly) CONSOLIDATE (nightly) RECALL (every prompt)
sessions → denoise score · reflect · link a compact index of
→ POST /distill decay · dedup · supersede relevant memories is
(one model, all phases) pushed into the prompt
→ full text lazy-loadedMemories strengthen when agents use them, fade when they don't, and link to related ones automatically. Retrieval is hybrid BM25 + vector search — zero-LLM at query time.
The first nightly run captures the last 7 days of sessions by default (not your entire history) — run hicortex nightly --recapture-window <days> once to import more.
Per-prompt recall push — relevant memory lands in context every turn; the agent fetches full content with hicortex_get only when it needs it.
Memory analytics at /dashboard — growth, recall adoption, and a nightly digest of what was learned.
Knowledge graph at /viz — memories clustered by domain, connected by relationship edges.
Domains & tags — multi-tag classification with a configurable vocabulary; your categories drift with your data.
Learnings from reflection — nightly reflection extracts general, reusable Learnings, not just Experience logs.
Self-correcting store — every night, stale facts are rewritten in place with dated provenance; near-duplicates resolve into one (verbatim copies kept free, merges recoverable); superseded decisions are demoted, never re-surfaced. No zombie memory.
Unprompted by design — coding agents get recall injected via hooks; instruction-capable clients (Claude Desktop, Cursor-class) get standing instructions, so memory is used without being asked. Plain MCP clients keep full search.
Self-calibrating — recall, decay and merge boundaries report their own statistics; tuning is measured, never guessed.
Standing context layer — hand-edited "who you are / how to work" Markdown, injected every session, never decayed.
Nine MCP tools — hicortex_search, hicortex_get, hicortex_recent, hicortex_ingest, hicortex_lessons, hicortex_index, hicortex_graph, hicortex_update, hicortex_delete — plus a /learn skill to save explicit learnings. Full reference →
TypeScript · Node.js 20+ · SQLite + sqlite-vec + FTS5 (semantic + full-text in one DB) · ONNX embeddings (bge-small-en, CPU) · MCP over HTTP/SSE · one configurable LLM (Ollama, Claude CLI, or any OpenAI-compatible endpoint).
git clone https://github.com/gamaze-labs/hicortex.git
cd hicortexAGENTS.md at the repository root defines the machine-checkable verification contract. "Done" means the full command chain exits with code 0. The contract mirrors what CI runs. Contributors — human or agent — run it before claiming work complete.
Contributions welcome — see CONTRIBUTING.md.
Website: hicortex.gamaze.com
Docs: hicortex.gamaze.com/docs
Changelog: CHANGELOG.md
npm: @gamaze/hicortex
Issues: gamaze-labs/hicortex/issues
Security: SECURITY.md
Personal and noncommercial use is free under the PolyForm Noncommercial License 1.0.0. Commercial use requires a per-seat license — see hicortex.gamaze.com.
Permanently delete a memory and its links. Use when a memory is incorrect and should be removed entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID (from search results, first 8 chars or full UUID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It says 'Permanently delete' which clearly communicates irreversibility, and it mentions that links are also deleted. This is a meaningful disclosure of destructive behavior beyond what the bare tool name implies. It does not mention error handling or return values, but for a simple delete operation with one parameter, this is adequate.
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 exactly two sentences with zero filler. The core action ('delete') and its scope are front-loaded in the first sentence, and the usage condition is succinctly stated in the second. Every word earns its place, making it highly efficient for an agent to parse.
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, no-output-schema tool, the description provides the essential context: what it does, its permanence, and when to use it. It does not explain what happens if the id is invalid or whether the operation is confirmed, but those details are not strictly necessary for the agent to decide to call it. The description is complete enough to guide correct invocation without ambiguity.
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 input schema already provides a thorough description of the 'id' parameter: 'Memory ID (from search results, first 8 chars or full UUID)'. The schema description coverage is 100%, so the description does not need to add parameter-level details. The description does not add any extra semantic nuance beyond what the schema gives, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('delete'), a clear resource ('a memory'), and an important scope ('and its links'). This distinguishes it from sibling tools like hicortex_update (which would modify) and hicortex_ingest (which adds). The agent can easily infer what this tool does without opening the schema.
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 provides an explicit condition for use: 'Use when a memory is incorrect and should be removed entirely.' This clearly implies when to use it (permanent removal) and implicitly covers when not to (e.g., for corrections, one would use update). It does not name an alternative tool explicitly, but the condition is sufficiently directive, earning a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch ONE memory's full content by id — use this to lazy-load entries from the '## Memory recall (auto)' index or from search results whose snippet was not enough. Fetching a memory marks it as used (strengthens it), so fetch entries that could change your action — not every shown one. When the memory shapes your answer, cite it to the user (id + date + origin agent) — mark a fetched memory FETCHED and a one-line entry cited unread SNIPPET; don't pass SNIPPET off as established.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory id (as shown in recall index/search results) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because no annotations are provided, the description carries the full burden of behavioral disclosure. It explicitly reveals the important side effect that fetching a memory marks it as used and strengthens it, and it also defines the citation conventions FETCHED vs SNIPPET. This goes well beyond a simple read-operation description.
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 dense but purposeful: it front-loads the core action, then adds usage caution, side-effect disclosure, and a citation rule. Every sentence contributes to correct invocation and follow-up behavior, with no filler or repetition of schema fields.
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 only one required parameter and no output schema, the description covers what is needed: what the tool returns ('full content'), when to call it, the side effect of calling it, and how to handle the result for citation. Nothing essential for correct use is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the id parameter is already described in the schema as 'Memory id (as shown in recall index/search results).' The description adds some context about where ids come from and what metadata is relevant for citation, but it does not fundamentally extend the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Fetch ONE memory's full content by id.' It also distinguishes itself from sibling tools by stating it is the lazy-load tool for entries from the '## Memory recall (auto)' index or insufficient search snippets, which is clearly different from index/search/recent listing tools.
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 explicit when-to-use guidance: lazy-load from the recall index or search results when the snippet was not enough. It also provides a clear exclusion—'not every shown one'—and advises fetching only entries that could change the agent's action, which serves as an effective decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query the memory knowledge graph — find connected memories, hub nodes, or paths between memories. Use it to explore memories connected to one you just fetched, or to find hub memories in a domain.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Memory ID (required for neighbors and path operations) | |
| limit | No | Max results (default 10) | |
| domain | No | Filter hubs by domain | |
| operation | Yes | Graph operation to perform | |
| target_id | No | Target memory ID (required for path operation) | |
| relationship | No | Filter neighbors by relationship type (e.g., extends, relates_to; legacy data may also have CONTRADICTS, SUPERSEDES, updates) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of implying side effects. The verbs 'Query' and 'explore' strongly indicate a read-only operation, and the listed operations (neighbors, hubs, path) are inherently non-mutating. It does not cover auth, limits, or output behavior, but it does enough to indicate the tool is safe to use for exploration.
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 crisp sentences with no filler. The core purpose is front-loaded, and the usage guidance is actionable. Every phrase 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?
Given the exhaustive schema, the description covers all three operations and their intended use cases. It does not describe output structure, but the tool has no output schema and the operation names make the return shape reasonably inferable. Slightly more explicit output guidance would make it fully complete.
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 already provides 100% parameter descriptions, including per-operation requirements and relationship examples, so the description does not need to re-explain parameters. The description adds conceptual linkage (e.g., 'connected to one you just fetched' implies id for neighbors; 'hub memories in a domain' implies the domain filter), but it does not materially improve on the schema's coverage.
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 uses a specific verb and resource ('Query the memory knowledge graph') and names the three distinct operations: neighbors, hubs, and paths. It differentiates the tool from siblings like hicortex_search and hicortex_get by focusing on graph relationships rather than flat retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage context: explore memories connected to a fetched one or find hub memories in a domain. It does not explicitly mention when not to use the tool or enumerate sibling alternatives, so it misses the 'when-not' guidance, but the intended use cases are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch your standing identity — the hand-edited 'who you are + how you work' layer (personality, rules, preferences). Returns all sections or a specific one. Use this to re-read your identity after context compaction or to look up a specific rule. On multi-agent installs, pass agent to fetch a specific agent's scoped identity; omit for the global identity.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Fetch a specific identity section by name (e.g. 'rules'). Omit for all sections. | |
| agent | No | Fetch a specific agent's identity scope (for per-agent installs). Omit for global. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does well: 'Fetch' signals a read operation, and it discloses the global vs. per-agent scoping behavior and the optional-section return behavior. It does not discuss side effects, but the read-only intent is clear from the verb and resource.
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 compact and well-structured: it states the resource, the return behavior, the primary use cases, and the parameter guidance in two sentences. Every sentence contributes actionable information with no 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 two-optional-parameter read tool with no output schema and no annotations, the description is complete. It explains the return shape, when to call, and how each parameter affects the result. The examples of section types ('personality, rules, preferences') give enough grounding for an agent to invoke 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that omitting `agent` returns the global identity and passing it fetches a scoped identity on multi-agent installs, and that omitting `name` returns all sections. This is meaningful semantic enrichment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'Fetch' and a clearly defined resource: the hand-edited identity layer covering personality, rules, and preferences. It distinguishes this from sibling tools by scoping it to the agent's own standing identity and explaining the 'all sections or a specific one' behavior.
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 explicit use cases: re-read identity after context compaction or look up a specific rule. It does not explicitly state when not to use it relative to siblings like hicortex_get or hicortex_search, but the usage context is specific enough to guide an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the knowledge domain index — shows what topics and projects are stored in memory, grouped by domain. Call before a broad search to see which knowledge domains exist, or when unsure what the memory covers.
| 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 burden of behavioral disclosure. It discloses what the tool returns (topics and projects grouped by domain) but doesn't explicitly state that it's a read-only, side-effect-free operation, nor does it describe limits, pagination, or the exact return structure. For a zero-parameter listing tool, this is adequate but not rich — an agent can't be certain there are no side effects or cost implications.
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, zero filler. The first sentence front-loads the verb and resource ('Get the knowledge domain index'), and the second delivers actionable usage guidance. Every word earns its place, and the structure is well-ordered with the core purpose first.
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 zero-parameter tool with no output schema and no nested objects, the description covers the essentials: what it does, what it returns conceptually, and when to call it. The only gap is the absence of a precise return-format description, but given the tool's simplicity and the lack of an output schema to lean on, this is a minor omission rather than a blocking one.
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?
With zero parameters, the baseline is 4 per the rubric. The schema is empty (100% coverage trivially), so there is no parameter meaning to add. The description's mention of what the index shows ('grouped by domain') is the closest thing to semantic context, and it doesn't conflict with or duplicate any schema content.
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 ('Get') and resource ('knowledge domain index'), and explains what it shows ('topics and projects stored in memory, grouped by domain'). It differentiates itself from the sibling search tool by framing itself as the index/browse operation rather than a retrieval or mutation tool, which is clear enough for an agent to select 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?
The description gives explicit when-to-use guidance: 'Call before a broad search to see which knowledge domains exist, or when unsure what the memory covers.' This is clear context, though it doesn't name alternatives explicitly (e.g., hicortex_search) or state when NOT to use it. It implies the relationship to search but doesn't spell out exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new memory in long-term storage. Use for Knowledge, Decisions, or Learnings. Capture is automatic (nightly) — use this ONLY for explicitly requested learnings, never routine content.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | Memory content to store | |
| project | No | Project this memory belongs to | |
| corrects | No | ID (8-char prefix or full UUID) of an existing memory this one CORRECTS — records a corrected_by link and retracts the old memory (deterministic, no LLM). Mutually exclusive with supersedes. | |
| supersedes | No | ID (8-char prefix or full UUID) of an existing memory this one SUPERSEDES — records a superseded_by link and marks the old memory superseded (deterministic, no LLM). Mutually exclusive with corrects. | |
| memory_type | No | Type of memory (default: Experience). Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term). |
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 states the main effect (stores a memory) and notes the automatic nightly capture as background, but does not mention potential side effects of corrects/supersedes (retraction), idempotency, authentication, or error behavior. The description is not misleading but lacks depth regarding the tool's broader behavioral impact.
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 deliver the core purpose and usage constraint with zero fluff. The critical usage caveat ('never routine content') is front-loaded, ensuring the agent sees it immediately. Every word 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?
For a create operation with no output schema, the description covers the essential context: what to store, when to use it, and when not to. It does not explain the memory_type default or the retraction semantics of corrects/supersedes, but these are already in the schema. Given the absence of annotations, the description is sufficient but could add a note about the return value or error handling to reach full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all five parameters (content, project, corrects, supersedes, memory_type) with clear descriptions. The description adds no additional parameter-level information, which is acceptable given full schema coverage; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core function: 'Store a new memory in long-term storage.' It specifies the content categories (Knowledge, Decisions, Learnings) and explicitly distinguishes it from automatic nightly capture. This is a specific verb-resource pair that leaves no ambiguity about what the tool does, and it differentiates from sibling tools like search, get, update, delete by focusing on ingestion.
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 provides explicit guidance: 'use this ONLY for explicitly requested learnings, never routine content.' It also explains that routine content is handled automatically (nightly), giving a clear alternative path. This is a strong when-to-use/when-not-to-use directive, far beyond a mere implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get actionable Learnings — auto-generated insights about mistakes to avoid. CALL THIS before retrying an approach that failed before, or when picking up work where past problems may have been recorded.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look back N days (default 7) | |
| project | No | Filter by project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. 'Get' implies a read-only retrieval and 'auto-generated insights' describes the content type, which is useful. Still, it does not disclose any behavioral details such as whether results are cached, how many results are returned, or whether any state changes occur. Acceptable but not rich.
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. The core purpose is front-loaded and the usage directive is immediate. Every sentence 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?
For a simple retrieval tool with two optional parameters, the description plus complete schema coverage is largely sufficient. It tells the agent what to retrieve, when to call it, and how to filter. The lack of output schema or mention of result format is a minor gap, but not critical for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already documented with defaults and meanings. The description adds framing around when to use the tool but does not add semantic detail about the days or project parameters beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb+resource: 'Get actionable Learnings — auto-generated insights about mistakes to avoid.' It communicates what the tool returns and why it exists, but it does not explicitly distinguish itself from sibling tools like hicortex_lessons, 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?
The description gives explicit when-to-use guidance: call this before retrying a previously failed approach or when picking up work where past problems may be recorded. However, it does not say when not to use it or name alternative tools, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get actionable Learnings from past sessions — call it before retrying an approach that failed before. (Alias for hicortex_learnings.)
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Look back N days (default 7) | |
| project | No | Filter by project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions the tool returns 'actionable Learnings' and its aliasing, but it does not disclose what the output format is, whether it is read-only or has side effects, any authentication requirements, or how the 'days' and 'project' parameters affect behavior. As a read-like operation, it is likely safe, but the lack of detail leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence and front-loads the core purpose. The phrase 'call it before retrying an approach that failed before' is actionable and earns its place. It could be slightly more structured with a separate note on aliasing, but overall it is concise and efficient.
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 tool's simplicity (2 parameters, no required params, 100% schema coverage), the description is adequate for basic selection, but it does not explain the return value or how results are ordered or filtered, which might be important for an agent deciding between this and 'hicortex_recent' or 'hicortex_search'. The alias note is useful but does not fully compensate for missing behavioral context.
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 description coverage is 100%, meaning both parameters ('days' and 'project') are described in the schema. The description does not add further semantics beyond the schema, so the baseline score of 3 applies. It could have provided examples of valid values or interaction between parameters, but it does not.
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 and resource ('Get actionable Learnings') and provides a use case ('before retrying an approach that failed before'). However, it does not distinguish it from its sibling 'hicortex_learnings' except by noting it is an alias, which is helpful but not sufficient to clarify when to use this tool versus the alias or other siblings like 'hicortex_recent' or 'hicortex_search'.
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 explicitly states when to use the tool ('before retrying an approach that failed before'), which is a clear usage context. It also mentions it is an alias for 'hicortex_learnings', implicitly guiding the agent to use either interchangeably, but it does not provide explicit conditions for choosing alternatives like 'hicortex_search' or 'hicortex_get'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent memories, optionally filtered by project. CALL THIS AT THE START of substantive work on a project to catch up on its latest state — cheaper than asking the user what happened.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: the server default) | |
| project | No | Filter by project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It signals a read-style operation through 'Get' and adds a cost trait ('cheaper'), but it does not explicitly state non-mutating behavior, ordering, or response characteristics. This is adequate but not rich.
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 with the core function front-loaded and the usage note placed immediately after. Every word earns its place with no 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 read tool with two optional params, the description plus schema is sufficient for an agent to call it correctly. It lacks a precise definition of 'recent' or output shape, but neither is essential for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds the idea of recency and project filtering but does not add meaning beyond that, matching the baseline for fully covered 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?
The description clearly states the action ('Get recent memories') and the optional project filter, so an agent can tell what the tool operates on. It does not explicitly contrast with siblings like hicortex_search or hicortex_get, so full differentiation 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?
The description gives explicit usage context: call at the start of substantive project work to catch up on latest state, and it is cheaper than asking the user. It does not mention when not to use it or point to alternatives, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search shared long-term memory (all agents, all sessions). CALL THIS BEFORE assuming, guessing, or asking the user about anything that may have come up before: prior decisions, preferences, project facts, people, hardware, past incidents. If you are about to write 'I don't have information about…', search first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default: the server default) | |
| query | Yes | Search query text | |
| project | No | Filter by project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses the scope (all agents, all sessions) which adds context, but it does not state whether the operation is read-only, how results are ordered, or what the return format is. A search operation implies safety, but the lack of explicit behavior disclosure leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences that front-load the purpose and then deliver a strong usage directive. Every word earns its place; no fluff 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 search tool with no output schema, the description should ideally explain what the agent will receive (e.g., list of memories, snippets, ordering). It also doesn't mention limitations or edge cases. It's adequate for when to use, but incomplete on mechanics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters (query, limit, project) with descriptions. The tool description adds no extra parameter semantics, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool searches shared long-term memory across all agents and sessions, distinguishing it from siblings like hicortex_get or hicortex_recent. The verb 'search' and resource 'shared long-term memory' are specific and 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?
Explicitly instructs to call before assuming, guessing, or asking the user about prior information, and even gives a trigger condition ('If you are about to write...'). However, it does not mention when not to use it or alternatives like hicortex_recent for recent items, so it stops short of full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing memory. Use after searching to fix incorrect information. If content changes, the embedding is re-computed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Memory ID (from search results, first 8 chars or full UUID) | |
| content | No | New content text | |
| project | No | New project name | |
| memory_type | No | New memory type. Accepted: Knowledge/Experience/Decisions/Learnings (legacy raw enum also accepted, normalized to the canonical term). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses that the embedding is re-computed when content changes, a valuable side-effect. However, it does not mention whether the update is partial, what happens if the id does not exist, or any auth requirements. For a mutation tool with zero annotation coverage, this is only partially transparent.
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: the action, the usage context, and a behavioral side-effect. Each sentence earns its place, and the key purpose is front-loaded. 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?
The description covers what the tool does, when to use it, and a key behavioral effect. With full schema coverage for parameters and no output schema requirement, this is adequate. It could additionally mention error behavior or non-content changes, but the essentials are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds no additional parameter-level meaning beyond the behavioral note that content changes trigger embedding re-computation. This meets the baseline for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Update an existing memory,' a specific verb + resource that clearly identifies the operation. It also distinguishes the tool from siblings like ingest (create), delete, and search by emphasizing 'existing memory' and 'fix incorrect information.'
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?
'Use after searching to fix incorrect information' provides clear contextual guidance on when to invoke this tool. It implies that search first, then update, but it does not explicitly name alternative tools or state exclusions such as 'use ingest for new memories.' This is clear but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.21.0hicortex_recent1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max results (default: server config recentLimit)"New value: +"Max results (default: the server default)"hicortex_search1 field changedInput schema / properties / limit / descriptionPrevious value: -"Max results (default: server config searchLimit)"New value: +"Max results (default: the server default)"v0.20.7hicortex_deletehicortex_gethicortex_graphhicortex_identityhicortex_indexhicortex_ingesthicortex_learningshicortex_lessonshicortex_recenthicortex_searchhicortex_updateScored across 11 tools
While most tools have distinct purposes (get vs search vs delete), hicortex_learnings and hicortex_lessons are exact duplicates — clear ambiguity. Also, hicortex_update and hicortex_delete could overlap if incorrect content might be better corrected than removed, though descriptions mitigate this. hicortex_graph and hicortex_index are distinct but could be confused for related discovery tasks.
All tool names start with 'hicortex_' followed by a single verb or noun (get, delete, search, recent, ingest, update, learnings, lessons, index, identity, graph). Pattern is mostly consistent, but 'learnings' vs 'lessons' are synonyms for the same action, creating redundancy rather than following the verb_noun pattern seen elsewhere (e.g., search is verb, index is noun). Minor inconsistency: verbs for actions, nouns for queries.
With 11 tools, the count is within the ideal range for a memory management system. The tool count feels reasonable for the scope: CRUD operations, search, recent memories, learnings, indexing, identity, and graph exploration. Only redundancy of learnings/lessons slightly inflates the count, but overall it's well-scoped.
The server appears to cover the core lifecycle of memories: create (ingest), read (get, search, recent, index, identity), update, delete. It also includes advanced features like learnings and graph exploration. The only gap is a lack of bulk operations (e.g., delete by filter, list all memories) or a way to export/import, but those are minor and not essential for the stated purpose.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
Shared memory for all your AI agents, your whole team and every MCP client — save, search, recall.
Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.
Persistent personal memory for AI assistants — save, search, and recall across every MCP client.
