Using Memorix through Cursor, Windsurf, Claude Code, Codex, or another AI coding agent? Read the Agent Operator Playbook for the agent-facing install, MCP, hook, and troubleshooting rules.
Memorix is a local-first memory control plane for coding agents.
It keeps project memory, reasoning context, Git-derived facts, and optional autonomous-agent state in one place so you can continue work across IDEs, sessions, terminals, and agent runs without losing project truth.
For most users, the default path is simple: use the local TUI/CLI or connect one IDE over stdio MCP. Treat HTTP as the shared-control-plane mode you opt into when you specifically want one long-lived background service, shared MCP access, or a live dashboard endpoint.
Related MCP server: Memryzed
Most coding agents remember only the current thread. Memorix gives them a shared, persistent memory layer across IDEs, sessions, and projects.
Tier | Clients |
★ Core | Claude Code, Cursor, Windsurf |
◆ Extended | GitHub Copilot, Kiro, Codex |
○ Community | Gemini CLI, OpenCode, Antigravity, Trae |
Core = full hook integration + tested MCP + rules sync. Extended = hook integration with platform caveats. Community = best-effort hooks, community-reported compatibility.
If a client can speak MCP and launch a local command or HTTP endpoint, it can usually connect to Memorix even if it is not in the list above yet.
Install globally:
npm install -g memorixInitialize Memorix config:
memorix initmemorix init lets you choose between Global defaults and Project config.
Memorix uses two files with two roles:
memorix.yml for behavior and project settings
.env for secrets such as API keys
Then pick the path that matches what you want to do:
You want | Run | Best for |
Interactive terminal workbench |
| Default starting point for local search, chat, memory capture, and diagnostics |
Quick MCP setup inside one IDE |
| Default MCP path for Cursor, Claude Code, Codex, Windsurf, Gemini CLI, and other stdio clients |
Dashboard + shared HTTP MCP in the background |
| A long-lived shared control plane for multiple clients and a live dashboard endpoint |
Foreground HTTP mode for debugging or a custom port |
| Manual supervision, debugging, custom launch control |
Most users should choose one of the first two options above. Move to HTTP only when you intentionally want one shared background service, multi-client MCP access, or a live dashboard endpoint.
Common paths:
Goal | Use | Why |
Work directly in the terminal |
| CLI/TUI is the primary product surface. |
Connect an IDE or coding agent over MCP |
| Start a lightweight memory session without joining Agent Team by default. |
Run autonomous multi-agent execution |
| Structured plan → spawn → verify → fix → review loop with CLI agents. |
Watch project memory and agent state in the browser |
| Standalone read-mostly dashboard for memory, sessions, and autonomous agent team state. |
Companion commands: memorix background status|logs|stop. For multi-workspace HTTP sessions, bind with memorix_session_start(projectRoot=...).
Deeper details on startup, project binding, config precedence, and agent workflows: docs/SETUP.md and the Agent Operator Playbook.
Running memorix without arguments opens an interactive fullscreen terminal UI (requires a TTY). Use it for chat with project memory, search, quick memory capture, diagnostics, background service control, dashboard launch, and IDE setup. Press /help inside the TUI for the current command list.
Single-shot chat (no TUI): memorix ask "your question".
Memorix exposes a CLI-first operator surface. Use it when you want to inspect or control the current project directly from a terminal. MCP remains the integration layer for IDEs and agents.
memorix session start --agent codex-main --agentType codex
memorix memory search --query "docker control plane"
memorix reasoning search --query "why sqlite"
memorix retention status
memorix team status
memorix task list
memorix audit project
memorix sync workspace --action scanThe CLI is intentionally task-shaped, not a 1:1 mirror of MCP tool names. Native capabilities are available through these namespaces: session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest. MCP stays available for IDEs, agents, and optional graph-compatibility tools.
Memorix now includes an official Docker path for the HTTP control plane.
Quick start:
docker compose up --build -dThen connect to:
dashboard: http://localhost:3211
MCP: http://localhost:3211/mcp
health: http://localhost:3211/health
Important: Docker support is for serve-http, not memorix serve. Project-scoped Git/config behavior only works when the container can see the repositories it is asked to bind.
Full Docker guide: docs/DOCKER.md
Add Memorix to your MCP client:
{
"mcpServers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}{
"mcpServers": {
"memorix": {
"transport": "http",
"url": "http://localhost:3211/mcp"
}
}
}The per-client examples below show the simplest stdio shape. If you prefer the shared HTTP control plane, keep the generic HTTP block above and use the client-specific variants in docs/SETUP.md.
{
"mcpServers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}claude mcp add memorix -- memorix serve[mcp_servers.memorix]
command = "memorix"
args = ["serve"]For the full IDE matrix, Windows notes, and troubleshooting, see docs/SETUP.md.
You want to... | Use this | More detail |
Save and retrieve project memory |
| |
Capture Git truth |
| |
Run dashboard + HTTP MCP |
| |
Keep memory-only sessions lightweight |
| |
Join the autonomous agent team |
| |
Run autonomous multi-agent work |
| |
Sync agent configs/rules |
| |
Use Memorix from code |
|
The most common loop is deliberately small:
memorix memory store --text "Auth tokens expire after 24h" --title "Auth token TTL" --entity auth --type decision
memorix memory search --query "auth token ttl"
memorix session start --agent codex-main --agentType codexWhen multiple HTTP sessions are open at once, each session should bind itself with memorix_session_start(projectRoot=...) before using project-scoped memory tools.
HTTP MCP sessions idle out after 30 minutes by default. If your client does not automatically recover from stale HTTP session IDs, set a longer timeout before starting the control plane:
MEMORIX_SESSION_TIMEOUT_MS=86400000 memorix background start # 24hAgent Team is not the normal memory startup path and it is not a chat room between IDE windows. Join only when you need tasks, messages, locks, or a structured autonomous-agent workflow. For real multi-agent execution, prefer:
memorix orchestrate --goal "Add user authentication" --agents claude-code,cursor,codexMemorix is designed to stay light during normal memory use:
stdio MCP starts on demand and exits with the client
HTTP background mode is one local Node process plus SQLite/Orama state
LLM enrichment is optional; without API keys, Memorix falls back to local heuristic dedup/search
the heavier paths are build/test, Docker image builds, dashboard browsing, large imports, and optional LLM-backed formation
On this Windows development machine, the healthy HTTP control plane was observed at about 16 MB working set after several hours idle. Treat that as a local observation, not a cross-platform guarantee. See Performance and Resource Notes for knobs and trade-offs.
Import Memorix directly into your own TypeScript/Node.js project — no MCP or CLI needed:
import { createMemoryClient } from 'memorix/sdk';
const client = await createMemoryClient({ projectRoot: '/path/to/repo' });
// Store a memory
await client.store({
entityName: 'auth-module',
type: 'decision',
title: 'Use JWT for API auth',
narrative: 'Chose JWT over session cookies for stateless API.',
});
// Search
const results = await client.search({ query: 'authentication' });
// Retrieve, resolve, count
const obs = await client.get(1);
const all = await client.getAll();
await client.resolve([1, 2]);
await client.close();Three subpath exports:
Import | What you get |
|
|
| Type-only — interfaces, enums, constants |
| MCP stdio entry point (not for programmatic use) |
flowchart LR
subgraph ING["Ingress"]
A["Git Hooks<br/>commit + ingest"]
B["MCP Tools<br/>search, store, recall"]
C["CLI / TUI<br/>operator workflows"]
D["Dashboard<br/>read-mostly project view"]
end
subgraph RUN["Runtime"]
E["stdio MCP Server<br/>memorix serve"]
F["HTTP Control Plane<br/>background / serve-http"]
G["Project Binding<br/>git root + config"]
end
subgraph MEM["Memory"]
H["Observation<br/>facts, gotchas, fixes"]
I["Reasoning<br/>why, trade-offs, risks"]
J["Git Memory<br/>commit-derived ground truth"]
K["Session + Agent Team<br/>opt-in tasks, locks, handoffs"]
end
subgraph PROC["Processing"]
L["Formation<br/>quality shaping"]
M["Embedding + Index<br/>hybrid retrieval"]
N["Graph Linking<br/>entity relations"]
O["Dedup + Retention<br/>consolidate over time"]
end
subgraph USE["Consumption"]
P["Search / Timeline / Detail"]
Q["Dashboard / Agent Team View<br/>read-mostly state"]
R["Recall / Handoff / Resume"]
S["Skills / Sync / Orchestrate"]
end
A --> E
B --> E
C --> E
D --> F
E --> G
F --> G
G --> H
G --> I
G --> J
G --> K
H --> L
H --> M
I --> L
I --> N
J --> M
J --> N
K --> O
H --> P
I --> P
J --> P
K --> Q
H --> R
I --> R
J --> R
K --> SMemorix is not a single linear pipeline. It accepts memory from multiple ingress surfaces, persists it across multiple substrates, runs several asynchronous quality/indexing branches, and exposes the results through retrieval, dashboard, and explicit Agent Team surfaces.
Observation Memory: what changed, how something works, gotchas, problem-solution notes
Reasoning Memory: why a choice was made, alternatives, trade-offs, risks
Git Memory: immutable engineering facts derived from commits
Default search is project-scoped
scope="global" searches across projects
Global hits can be opened explicitly with project-aware refs
Source-aware retrieval boosts Git memories for "what changed" questions and reasoning memories for "why" questions
📖 Docs Map — fastest route to the right document.
Section | What's Covered |
Install, stdio vs HTTP control plane, per-client config | |
Official container image path, compose, healthcheck, and path caveats | |
Resource profile, idle/runtime costs, optimization knobs | |
| |
Canonical AI-facing guide for installation, binding, hooks, troubleshooting | |
System shape, memory layers, data flows, module map | |
MCP / HTTP / CLI command surface | |
Ingestion, noise filtering, retrieval semantics | |
Contributor workflow, build, test, release |
Additional deep references:
Version 1.0.8 builds on the 1.0.7 coordination/storage/team baseline with a CLI-first operator surface, official Docker path, dashboard refinements, and broad hooks fixes.
CLI-First Product Surface: Every Memorix-native operator capability now has a task-oriented CLI route — session, memory, reasoning, retention, formation, audit, transfer, skills, team, task, message, lock, handoff, poll, sync, ingest. MCP remains the integration protocol and optional graph-compatibility layer.
Docker Deployment: Official Dockerfile, compose.yaml, healthcheck, --host binding, and DOCKER.md for running the HTTP control plane in a container.
Multi-Agent Orchestrator: memorix orchestrate runs plan, parallel execution, verification, fix, review, and merge loops across Claude, Codex, Gemini CLI, and OpenCode with capability routing, worktree isolation, and agent fallback.
SQLite Canonical Store: Observations, mini-skills, sessions, and archives in SQLite. Shared DB handle, freshness-safe retrieval, dead JsonBackend removed.
Opt-in Agent Team: task board, messages, file locks, handoff artifacts, and autonomous-agent heartbeat state. session_start is lightweight by default; team identity is opt-in via joinTeam or team_manage join.
Dashboard Semantic Layering: Team page filter tabs (Active/Recent/Historical), de-emphasized historical agents, project switcher grouped by real/temporary/placeholder, identity page cleanup.
Hooks Fixes: OpenCode event-name key mapping + Bun.spawn → spawnSync; Copilot pwsh fallback + global-hooks guard; hook handler diagnostic logging.
Programmatic SDK: import { createMemoryClient } from 'memorix/sdk' to store, search, get, and resolve observations directly from your own code without MCP or CLI. Also exports createMemorixServer and detectProject.
Test Suite Stabilization: E2e and live-LLM tests are excluded from the default suite, and load-sensitive tests are isolated so the default verification path stays deterministic.
git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install
npm run dev
npm test
npm run buildKey local commands:
memorix status
memorix dashboard
memorix background start
memorix serve-http --port 3211
memorix git-hook --forceMemorix builds on ideas from mcp-memory-service, MemCP, claude-mem, Mem0, and the broader MCP ecosystem.
Show CodeGraph Memory provider and index status for the current project.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description implies a read-only operation ('Show'), but does not explicitly confirm no side effects or provide additional behavioral context.
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, clear sentence with no unnecessary words. Perfectly concise for a tool with no parameters.
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 is adequate for a simple status tool, but it does not explain what 'provider and index status' entails or what the output looks like. Could be improved with more detail.
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 and 100% schema coverage, the description adds no parameter-specific meaning beyond the schema. Baseline score 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 uses a specific verb ('Show') and identifies a clear resource ('CodeGraph Memory provider and index status') scoped to 'the current project'. It clearly distinguishes the tool's single purpose.
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 use this tool versus its siblings. The description does not mention any prerequisites or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a prompt-ready working context pack for a coding task. Combines relevant memories, CodeGraph Memory facts, freshness warnings, suggested reads, and verification hints. After a complete memorix_project_context brief, provide purpose only when deliberately expanding beyond it.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Current coding task or question | |
| limit | No | Max active memories to inspect before code-ref filtering (default: 20) | |
| purpose | No | Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user's explicit request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions the output includes memories, facts, warnings, etc., but does not specify any side effects, permissions, or limitations. The behavioral transparency is adequate but not detailed.
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 sentence plus a brief instruction, very concise with no wasted words. It efficiently communicates the tool's purpose and key usage note.
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?
Despite having no output schema and no annotations, the description gives a good overview of what the tool does. However, it lacks details on the exact output format, pagination, or error handling, leaving some gaps for an agent to fully understand the tool's behavior.
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 each parameter has a description. The tool description adds meaningful context for the 'purpose' parameter by explaining when to provide it, which goes beyond the schema description. This enhances understanding.
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 it builds a context pack for a coding task, combining several elements. It also differentiates from the sibling 'memorix_project_context' by specifying when to provide the 'purpose' parameter. However, it does not explicitly distinguish from all other siblings, leaving some ambiguity.
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 implies use for coding tasks and after a project context brief, but lacks explicit guidance on when not to use this tool or which alternatives to consider. Given the many sibling tools, more clarity would be beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch full observation, mini-skill, or curated durable-memory details — includes source kind (explicit memory / hook trace / git evidence), value category, and cross-references (~500-1000 tokens each). Do not re-fetch content already covered by a complete memorix_project_context brief unless a specific fact is still missing or the user asks for deeper history; provide purpose when intentionally expanding. Always use memorix_search first to find relevant IDs, then fetch only what you need. Accepts typed refs from search results (e.g. "obs:42", "skill:3") and durable refs from a project brief (e.g. "durable:") via the typedRefs field, or legacy numeric ids / object refs for backward compatibility.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Observation IDs to fetch (legacy, from memorix_search results) | |
| refs | No | Explicit observation refs. Prefer this for global search results. | |
| force | No | Use only when the user explicitly asks to read a record already represented in the latest Autopilot brief. | |
| purpose | No | Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user's explicit request. | |
| typedRefs | No | Typed memory refs from search results or a project brief, e.g. "obs:42", "skill:3", "durable:<uuid>", "obs:42@org/proj" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses what the tool returns (source kind, value category, cross-references, ~500-1000 tokens each) and warns against redundant fetching. It does not cover error handling or permissions, but for a read-only detail-fetch tool 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 three dense sentences, front-loaded with the primary action ('Fetch full observation...'). Each sentence adds distinct value—scope, usage rules, and accepted input formats—without obvious redundancy. It is slightly longer than minimal, but the additional guidance 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 there is no output schema, the description fills the gap by explaining the contents of the return (source kind, value category, cross-references) and the expected token range. It also covers the full input-ref landscape and usage context, making the tool comprehensible without needing further documentation.
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?
All five parameters already have schema descriptions (100% coverage), and the description adds meaningful usage context beyond the schema. It explains typedRefs (obs:42, skill:3, durable:<uuid>) versus legacy numeric ids/object refs, and clarifies when the purpose and force fields should be used. This helps the agent select the correct parameter for each situation.
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 'Fetch full observation, mini-skill, or curated durable-memory details,' which clearly states the verb and targeted resources. It distinguishes from siblings by referencing memorix_search for finding IDs and memorix_project_context for briefs, making it clear this tool provides the detailed record 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?
Explicit guidance is provided: 'Always use memorix_search first to find relevant IDs, then fetch only what you need' and 'Do not re-fetch content already covered by a complete memorix_project_context brief unless a specific fact is still missing or the user asks for deeper history.' These quoted rules give direct when-to-use and when-not-to-use instructions, along with the expectation to provide a purpose when intentionally expanding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use the controlled local media library for an explicit import, attachment, inspection, or MiniMax generation request. Assets stay outside the Git worktree and enter normal memory only when attach is explicitly true. Use the CLI for destructive removal, quota cleanup, and direct generation. MCP generation is disabled by default and requires MEMORIX_MCP_MEDIA_GENERATION=1 after the operator reviews provider billing.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Optional asset list filter. | |
| path | No | Explicit local image/audio/video/PDF path for import. | |
| jobId | No | Durable media job ID for status. | |
| limit | No | Maximum assets to list. | |
| title | No | Observation title when attaching generated/imported output. | |
| action | Yes | ||
| attach | No | Attach generated/imported output to normal project memory explicitly. | |
| assetId | No | Controlled MediaAsset ID for attach/show. | |
| maxChars | No | Bounded PDF extraction character limit. | |
| maxPages | No | Bounded PDF extraction page limit. | |
| narrative | No | Short retrieval text when attaching an asset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and does well: it discloses that assets remain outside the Git worktree, enter normal memory only when attach is explicitly true, and that generation is disabled by default pending billing review. This goes well beyond the schema, though it doesn't enumerate per-action side effects or authentication 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?
The description is four focused sentences with the purpose front-loaded. Every sentence adds value: storage location, attach condition, CLI alternative, and generation gating. No filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 11-parameter, 7-action tool with no output schema, the description provides essential policy context and the schema covers parameter details. It misses explicit per-action return behavior and authentication, but the combination of schema richness and behavioral warnings is adequate for most agent decision-making.
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 91%, so the parameters are already well documented and the baseline is 3. The description adds the important semantic that attach=true is the trigger for entering normal memory, but it doesn't otherwise explain parameter interactions or syntax.
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 set ('import, attachment, inspection, or MiniMax generation') tied to the 'controlled local media library', and the title 'Manage Controlled Media' reinforces the resource. This clearly differentiates the tool from the sibling memory/search 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?
It explicitly states when to use the MCP tool versus the CLI: use the CLI for destructive removal, quota cleanup, and direct generation. It also explains the conditional enablement of MCP generation (MEMORIX_MCP_MEDIA_GENERATION=1, operator billing review), providing clear when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build a compact Memory Autopilot brief for the current coding task. Schedules Code Memory refresh when needed, includes Start here files, reliable code-bound memories, stale/suspect cautions, and verification hints. Use this at the start of a new coding turn or after switching tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Current coding task or question | |
| agent | No | Optional target agent for compatible workflow selection. | |
| limit | No | Reserved for future source limits; current prompt stays compact by default. | |
| format | No | Output format. "prompt" is agent-ready; "summary" is human-readable; "receipt" is bounded JSON; "json" is detailed diagnostics. | prompt |
| taskId | No | Optional task continuity ledger id to include in the brief | |
| refresh | No | Code Memory refresh policy. auto refreshes only when missing or stale. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose a non-obvious side effect: the tool "schedules Code Memory refresh when needed," which tells the agent this is not a pure read. It also previews the output composition (stale/suspect cautions, verification hints), so the agent knows to expect warnings rather than raw data. It omits cost/latency and whether the scheduled refresh mutates stored memory, which keeps it below a 5.
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 sentences, front-loaded with the purpose, then the contents, then the trigger condition. No filler and no repetition of schema fields. The contents list is dense but every item conveys what the agent will receive.
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?
Six optional parameters, all fully described in the schema, and the description explains what the brief contains, which substitutes for the absent output schema. What remains unclear is the relationship to overlapping siblings (context_pack, session_start) and whether the refresh side effect persists state. For a tool of this complexity that is a minor gap, not 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?
Schema description coverage is 100%, including enum explanations for agent, format, and refresh, so the schema already documents every parameter. The description adds no parameter-level meaning beyond a general note that the prompt stays compact, which the schema already states for limit. Baseline 3 applies when structured fields do the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and artifact: "Build a compact Memory Autopilot brief for the current coding task," then enumerates what the brief contains (Start here files, code-bound memories, cautions, verification hints). That content list does most of the work of separating it from siblings, but it never names or contrasts with the closest-looking sibling, memorix_context_pack, leaving the agent to infer the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger: "Use this at the start of a new coding turn or after switching tasks." That is clear when-to-use guidance. It stops short of when-not-to-use or naming alternatives (e.g. when context_pack or session_start is the better call), so it is not a full routing rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark observations as resolved (completed/no longer active). Resolved memories are hidden from default search but can still be found with status="all". Use this to mark completed tasks, fixed bugs, or outdated information so they don't pollute future context.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | Observation IDs to mark as resolved | |
| status | No | Target status: "resolved" (default, completed/done) or "archived" (permanently hidden) | resolved |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains key behavioral traits: that resolved memories are hidden from default search, can still be found with status='all', and the purpose is to prevent pollution of future context. It doesn't mention permissions, rate limits, or whether the operation is reversible, but provides substantial operational context.
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 efficiently structured in two sentences: the first states the core action and effect, the second provides usage examples and rationale. Every sentence earns its place with no wasted words, and key information is front-loaded.
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 and no output schema, the description provides good context about the operation's purpose and effects. It explains the behavioral consequences (hidden from default search, findable with status='all') and practical use cases. However, it doesn't describe what the tool returns or potential error conditions.
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%, providing complete parameter documentation. The description adds some value by explaining the purpose of marking observations as resolved and the effect on search, but doesn't provide additional parameter-specific semantics beyond what the schema already documents (like explaining the difference between 'resolved' and 'archived' statuses).
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 purpose with specific verb ('mark as resolved') and resource ('observations'), and distinguishes it from siblings by explaining what resolved memories are (hidden from default search but findable with status='all'). It provides concrete examples of use cases (completed tasks, fixed bugs, outdated 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?
The description provides clear context for when to use this tool (to mark completed tasks, fixed bugs, or outdated information) and explains the effect (so they don't pollute future context). However, it doesn't explicitly state when NOT to use it or name specific alternative tools among the many siblings, though it implies search tools might be alternatives for finding resolved items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search project memory. Returns a compact index (~50-100 tokens/result). Do not use as a follow-up to a complete memorix_project_context brief unless a specific fact is still missing or the user asks for deeper history; provide purpose when intentionally expanding. Use memorix_detail to fetch full content for specific IDs. Use memorix_timeline to see chronological context. Searches across all observations stored from any IDE session — enabling cross-session and cross-agent context retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Filter by observation type | |
| force | No | Use only when the user explicitly asks to read a record already represented in the latest Autopilot brief. | |
| limit | No | Max results (default: 20) | |
| query | Yes | Search query (natural language or keywords) | |
| scope | No | Search scope: "project" (default) only searches current project, "global" searches all projects | project |
| since | No | Only return observations created after this date (ISO 8601 or natural like "2025-01-15") | |
| until | No | Only return observations created before this date (ISO 8601 or natural like "2025-02-01") | |
| source | No | Filter by memory source. "git" returns only commit-derived ground truth memories. Omit for all sources. | |
| status | No | Filter by memory status. "active" (default) shows current memories, "all" includes resolved/archived. | active |
| purpose | No | Why this must expand beyond the latest Autopilot brief. Name the missing fact or the user's explicit request. | |
| quality | No | Retrieval profile: fast stays local, balanced uses configured embeddings, thorough explicitly permits optional LLM refinement. | balanced |
| maxTokens | No | Token budget — trim results to fit (0 = unlimited) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses return format (compact index, token size), search scope (cross-session/cross-agent), and it implies read-only behavior. Lacks explicit safety or permission info, but acceptable for a search 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?
Two sentences plus guidance on usage; front-loads purpose, then usage and alternatives. No wasted words, every sentence adds value.
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 12 parameters, no output schema, and moderate complexity, the description covers purpose, usage, and return characteristics well. Minor gaps: no explanation of purpose field usage or behavior when omitted, but overall complete for a search 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?
Schema coverage is 100% with descriptions for all 12 parameters. The tool description does not add significant meaning beyond the schema, only gives context on return format. Baseline 3 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?
Clearly states 'Search project memory' with verb and resource, mentions return format as compact index (~50-100 tokens/result), and distinguishes from siblings (memorix_detail, memorix_timeline).
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 warns against using as follow-up to a complete brief unless a specific fact is missing, provides purpose requirement, and names alternatives (memorix_detail for full content, memorix_timeline for chronology).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a new coding session. Returns a compact continuation card with the latest handoff and a few memory references. Call this at the beginning of a session to track activity; retrieve a referenced memory only when it is relevant. Any previous active session for this project will be auto-closed. By default this is lightweight: it binds the project, opens a session, and avoids dumping full history into the new context. Coordination identity is opt-in via joinTeam: true or a separate team_manage join call.
IMPORTANT for HTTP/control-plane mode: pass projectRoot with the absolute path to your workspace root (e.g., the directory open in your IDE). Memorix uses this to detect the git project and bind this session to the correct project context. Without it, project-scoped tools will be disabled.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Explicit role override used only when joinTeam=true. | |
| agent | No | Agent/IDE name (e.g., "cursor", "windsurf", "claude-code") | |
| joinTeam | No | If true, also join orchestration coordination state for this session. Defaults to false. | |
| agentType | No | Agent type used for optional coordination identity mapping (e.g., "windsurf", "cursor"). | |
| sessionId | No | Custom session ID (auto-generated if omitted) | |
| instanceId | No | Stable instance ID for optional coordination identity across restarts. If omitted with joinTeam=true, Memorix derives a deterministic fallback from the project and agent identity. | |
| projectRoot | No | Absolute path to the workspace/project root directory (e.g., the folder open in your IDE). Memorix will detect the git project from this path and bind this session to it. Required for HTTP transport when multiple projects are open simultaneously or when rebinding an existing control-plane session. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: auto-closes previous active sessions, is lightweight (no history dump), and coordination identity is opt-in. No annotations provided, so description covers behavioral traits fully.
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?
Clear and front-loaded with key information, but contains some redundancy (e.g., coordination identity mentioned twice). Could be slightly more concise.
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?
Covers return value, side effects (auto-close), important HTTP mode notes, and default behavior. Adequate for a tool with no output schema and 7 parameters.
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 has 100% coverage, baseline 3. Description adds context beyond schema, e.g., `projectRoot` is critical for HTTP mode and `role` is only used when `joinTeam=true`. However, not all parameters are elaborated.
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 explicitly states it starts a new coding session, returns a compact continuation card, and tracks activity. It distinguishes from siblings like memorix_session_end and memorix_session_context by its unique role as the session starter.
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 clear when-to-use instruction ('at the beginning of a session'), important HTTP mode requirements, and mentions alternatives like `joinTeam: true` or `team_manage` for coordination identity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a new observation/memory. Automatically indexed for search. Use type to classify: gotcha ([GOTCHA] critical pitfall), decision ([DECISION] architecture choice), problem-solution ([FIX] bug fix), how-it-works ([INFO] explanation), what-changed ([CHANGE] change), discovery ([DISCOVERY] insight), why-it-exists ([WHY] rationale), trade-off ([TRADEOFF] compromise), session-request ([SESSION] original goal). Project visibility is the default. Personal or team visibility requires an explicitly joined coordination identity. Set longTerm only when the caller explicitly wants an additional source-backed long-term candidate; it is never injected until an operator records a review through the CLI. For a read-only task, do not store unless the user explicitly asks to save a record.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Observation type for classification | |
| facts | No | Structured facts (e.g., "Default timeout: 60s") | |
| title | Yes | Short descriptive title (~5-10 words) | |
| concepts | No | Related concepts/keywords | |
| longTerm | No | Optional explicit request to create a source-backed long-term candidate alongside this observation. Candidates are not automatically injected. | |
| progress | No | Progress tracking for task/feature observations | |
| topicKey | No | Optional topic identifier for upserts (e.g., "architecture/auth-model"). If an observation with the same topicKey already exists in this project, it will be UPDATED instead of creating a new one. Use memorix_suggest_topic_key to generate a stable key. Good for evolving decisions, architecture docs, etc. | |
| narrative | Yes | Full description of the observation | |
| entityName | Yes | The entity this observation belongs to (e.g., "auth-module", "port-config") | |
| visibility | No | Retrieval scope. Project is the normal shared default; personal/team require memorix_session_start with joinTeam=true. | |
| attachments | No | Safe public provenance references. They are stored as metadata for lexical retrieval; raw inline media is never stored. | |
| filesModified | No | Files involved | |
| relatedCommits | No | Git commit hashes this memory relates to (links ground truth ↔ reasoning) | |
| relatedEntities | No | Other entity names this memory cross-references | |
| overrideReadOnly | No | Use only when the user explicitly asks to save memory during a read-only or no-modification task. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses auto-indexing, type classification prefixes, default visibility, visibility requirements (personal/team require joined coordination identity), longTerm not injected until operator review, and the read-only guard. This adds significant context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but front-loaded with the core purpose. The type list is long but valuable. No fluff; every sentence adds functional information. Slightly long due to the type enumeration, but well-structured for 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?
For a complex tool with 15 parameters and no output schema, the description covers essential operational context (type, visibility, longTerm, read-only) while the schema descriptions cover remaining parameters. It does not mention upsert behavior of topicKey or attachment constraints, but these are in schema. Overall, sufficiently complete for safe 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 coverage is 100%, so baseline is 3. The description adds meaning beyond schema for key parameters: explains the type enum with bracketed prefixes and meanings (e.g., gotcha = critical pitfall), clarifies visibility defaults and requirements, and details longTerm semantics. This meaningfully enriches the 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 clearly states the tool's function: 'Store a new observation/memory. Automatically indexed for search.' This gives a specific verb and resource. However, it does not explicitly differentiate from sibling tool memorix_store_reasoning, which may be a related but distinct store operation.
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 explicit when-to-use and when-not-to-use guidance: 'For a read-only task, do not store unless the user explicitly asks to save a record.' Also gives conditions for longTerm: 'Set longTerm only when the caller explicitly wants an additional source-backed long-term candidate.' This is strong usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.10.3memorix_project_context1 field changedInput schema / properties / refresh / defaultRemoved value: -"auto"v1.9.5memorix_project_context1 field changedInput schema / properties / taskIdAdded value: +{
+ "description": "Optional task continuity ledger id to include in the brief",
+ "maxLength": 120,
+ "type": "string"
+}Scored across 9 tools
Most tools map to distinct memory operations, but memorix_project_context, memorix_context_pack, and memorix_session_start all produce starting context with overlapping contents. The descriptions attempt a hierarchy, yet an agent can still hesitate between them for initial context gathering.
All tools use the memorix_ prefix and snake_case naming consistently. The noun-style names like memorix_detail and memorix_media remain predictable within the set.
Nine tools is well within a reasonable range for a project-memory and context server. Each broad capability—search, store, detail, resolve, session, context, status, media—has a distinct role.
Core create/read/resolve/session workflows are present, but there is no update operation and destructive removal is pushed to the CLI. Search explicitly references memorix_timeline and session_start references team_manage, neither of which is exposed, creating dead-end guidance.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
