Memorix is a local-first, cross-agent memory and orchestration layer for AI coding agents, providing persistent context, multi-agent coordination, and memory management across IDEs and sessions.
Core Memory Operations
Store observations, decisions, gotchas, bug fixes, and discoveries with entity tagging, file references, and topic keys for upserts
Search memories via natural language or keyword, with filters for type, date range, and status
Fetch details for specific memory IDs; view timeline context (before/after a given observation)
Resolve/archive outdated or completed memories to keep context clean
Suggest topic keys to avoid duplicates on evolving topics
Memory Quality & Maintenance
Deduplicate — LLM-assisted or heuristic scanning and resolution of duplicate/contradictory memories
Consolidate — Merge similar observations by entity+type to reduce bloat
Retention management — Monitor memory health via exponential decay scoring and archive expired entries
Promote to mini-skills — Elevate key observations to permanent skills injected at every session start
Session Lifecycle
Start/end coding sessions with structured summaries (goal, discoveries, accomplishments, files) for seamless handoff
Recover previous session context after compaction or context loss
Workspace & Rules Sync
Sync and deduplicate agent rule files across Cursor, Claude Code, Codex, Windsurf, Copilot, Kiro, and more
Migrate MCP configs, workflows, rules, and skills between AI coding agents (scan, preview, or apply)
List, auto-generate, or inject project-specific skills derived from memory patterns
Agent Team Coordination
Register/unregister agents and list active team members with roles
Acquire/release advisory file locks (auto-expiring) to prevent conflicting edits
Create, claim, complete, and list tasks with dependency tracking across agents
Send direct or broadcast messages between agents
Data & Dashboard
Export/import observations and sessions as JSON or Markdown
Launch a local web dashboard to visualize knowledge graphs, retention scores, sessions, and agent team state
Integrates with the Windsurf IDE to provide cross-agent memory, multi-agent coordination, and project-specific knowledge retrieval.
Allows for local semantic embeddings and search enhancements using local Ollama-compatible endpoints.
Provides support for semantic vector search, intelligent narrative compression, and result reranking via OpenAI-compatible APIs.
Maintainer status and the current public work boundary live in ACTIVE_WORK.md. It is the repository's single living work tracker.
Memorix gives the AI coding agents you already use a shared, searchable project memory that survives new chats, IDE switches, terminal sessions, and handoffs. The memory lives under the Git project, not inside one chat window or one tool.
Use Claude Code today, Codex tomorrow, and Cursor in the afternoon. The agent can change; the project memory stays the same.
Use Memorix when you keep re-explaining the same project to a new agent session: the last session already figured something out, another IDE cannot see it, or a design decision is buried in a chat you cannot find anymore.
Problem | What Memorix adds |
The next session forgets what the last session learned | Project-scoped memory, session summaries, timelines, and detail retrieval |
Different agents know different things | One local memory pool available through MCP, hooks, CLI, SDK, and the bundled terminal agent |
Git records what changed, but agents cannot recall it well | Git Memory turns commits into searchable engineering facts |
Architecture decisions disappear into old chats | Reasoning Memory stores why choices were made, with alternatives and trade-offs |
Static rule files drift | Gotchas, fixes, and project skills evolve from real work |
Parallel agent work gets messy |
|
Memorix is local-first. SQLite is the canonical store, Orama handles search, and LLM-backed formation/embedding is optional. Without model keys, Memorix still works with local full-text retrieval.
Memorix is more than a memory store. It also installs agent integrations, keeps useful work events, turns commits into project facts, exposes a local control plane, and can coordinate multi-agent work when a task needs it.
Capability | What it does | Entry point |
Memory Autopilot | A bounded task Workset with start files, current memory, source-backed knowledge, workflow starts, cautions, and verification. Compact JSON receipts keep fallback CLI use bounded too. |
|
Observation Memory | Searchable facts, fixes, gotchas, session summaries, and implementation notes scoped to the current Git project |
|
Curated Long-term Memory | Deliberately reviewed episodic, semantic, and procedural memory with source evidence. Only an explicitly portable user item can cross local projects |
|
Code State and Code Memory | Versioned local code snapshots, source-backed TypeScript/JavaScript symbols and relations, file/symbol links, and freshness checks. Other languages keep the honest Lite fallback; an already-indexed local CodeGraph or SCIP result can add a bounded external outline without taking over the local index. |
|
Git Memory | Commit-derived engineering facts that answer what changed, where, and why it matters |
|
Reasoning Memory | Design rationale, alternatives, trade-offs, and risks that should survive beyond one chat |
|
Knowledge Workspace | Review-gated source-backed claims, Markdown pages, and canonical project workflows; proposals never overwrite reviewed pages silently |
|
Agent setup | One setup path for MCP, rules, hooks, skills, plugins, bundles, or extensions depending on the agent |
|
Agent doctor | Checks whether agent MCP config and guidance are current, then repairs Memorix-owned entries when needed |
|
Hooks and skills | Optional capture from supported agents, plus reusable project skills promoted from durable knowledge |
|
Dashboard and HTTP | A local web UI and shared MCP endpoint for browsing memory, project state, teams, diagnostics, and preview-first cleanup, consolidation, deduplication, and retention actions |
|
Orchestration and team work | Task planning, worker handoffs, file locks, messages, verification gates, and review loops |
|
memcode | A bundled terminal coding agent that already reads and writes the same project memory |
|
CLI and SDK | Scriptable access for automation, imports/exports, diagnostics, and custom integrations |
|
Memorix connects through the interfaces each agent already supports: plugin packages, MCP, project rules, hooks, skills, or the bundled terminal agent. memorix setup chooses the right setup for each agent and keeps stdio MCP as the default transport.
Integration surfaces:
Surface | What it does | Memorix entry |
Setup command | Installs the recommended one-time user-level Memorix integration |
|
MCP | Gives an agent compact Memorix tools for project context, search, detail retrieval, storage, and resolution | bundled in setup packages or |
Usage guidance | Teaches an agent when and how to use Memorix without forcing memory lookup on every prompt | bundled or generated by |
Hooks | Optional capture of prompts, tool events, file edits, session lifecycle events, and native compaction checkpoints where the agent exposes them | bundled or generated by |
Plugin or bundle package | Installs plugin, compatible-bundle, or package files where the agent supports them | Claude Code, Codex, CodeBuddy Code, GitHub Copilot CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi |
Extension | Installs extension files where the agent supports them | Gemini CLI |
Local plugin | Installs local plugin files where the agent loads them directly | OpenCode |
MCP/rules config | Writes MCP, rules, steering, guidance, or hook config for IDEs and agents that expose those surfaces | Cursor, Windsurf, Kiro, Trae, DeepSeek Harness, WorkBuddy |
Skills | Turns durable project knowledge into reusable task guidance |
|
memcode | Opens the bundled terminal agent that already uses Memorix memory |
|
See Integration Surfaces for the current support matrix and what each generated file means.
Use the same setup command without --global only when you intentionally want repo-local guidance, rules, or hooks in the current Git project.
CLI, MCP, and HTTP are different entry points:
memorix CLI is the direct command surface for setup, memory search/store, Git Memory, import/export, dashboard, orchestration, diagnostics, and automation.
memorix serve is the stdio MCP bridge used by IDEs and coding agents. Its default tool profile is micro, so agents see only the compact core tool set.
memorix background start / memorix serve-http run the HTTP service for a shared endpoint, dashboard, VPS Docker deployment, or multiple clients.
Requirements:
Node.js >=22.18.0
Git, because project identity is derived from the real Git root
Install and initialize:
npm install -g memorix
memorix init --global # optional defaults
memorix setup --agent claude --global # or codex, copilot, cursor, pi, gemini-cli, opencode,
# codebuddy, windsurf, kiro, antigravity, trae, openclaw, hermes, ompmemorix init is optional. It creates or updates TOML configuration:
~/.memorix/config.toml for global defaults
<git-root>/memorix.toml for optional project overrides
Legacy memorix.yml, .env, and ~/.memorix/config.json are still read for compatibility, but new setup flows use TOML.
If you want repo-local guidance or hooks for a specific repository, run the same setup command from inside that repo without --global. Codex is the exception: its supported path is the user-level plugin install, so Memorix leaves project .codex configuration alone.
Use the setup command first. The global form is the normal one-time install:
memorix setup --agent claude --global
memorix setup --agent codex --global
memorix setup --agent copilot --global
memorix setup --agent cursor --global
memorix setup --agent pi --global
memorix setup --agent gemini-cli --global
memorix setup --agent opencode --global
memorix setup --agent windsurf --global
memorix setup --agent kiro --global
memorix setup --agent antigravity --global
memorix setup --agent trae --global
memorix setup --agent openclaw --global
memorix setup --agent hermes --global
memorix setup --agent codebuddy --global
memorix setup --agent omp --global
memorix setup --agent dsh --global
memorix setup --agent workbuddy --globalWhat it installs depends on the target agent, but the goal is the same: make Memorix available wherever you open that agent without asking you to wire every repo by hand.
Claude Code: installs the Memorix plugin package, adds CLAUDE.md guidance, and enables hook capture when you do not pass --noHooks.
Codex: installs one user-level Memorix plugin with bundled stdio MCP, skills, and lifecycle hooks. It does not write project-local .codex config or change your model, approval, or sandbox settings. When Codex asks, review the plugin hook definition once with /hooks; --noHooks skips automatic capture.
GitHub Copilot CLI: installs the Copilot plugin package and official Memorix skills.
Pi: installs the user-level Pi package and official skills.
Cursor: writes Cursor MCP/rules/config entries in the chosen scope.
Gemini CLI: installs the extension package, GEMINI.md context, hooks, and skills. Antigravity CLI has an official Gemini CLI migration path, but Gemini CLI remains an active standalone target.
OpenCode: installs the local plugin file, opencode.json, skills, and AGENTS.md guidance.
Windsurf, Kiro, Trae: write the MCP/rules/hooks files the target supports.
Antigravity: installs the official plugin package with plugin.json, mcp_config.json, hooks.json, rules, and skills under ~/.gemini/config/plugins/memorix or .agents/plugins/memorix.
OpenClaw: installs an OpenClaw-compatible bundle with .mcp.json, official skills, and an OpenClaw HOOK.md/handler.ts hook pack.
Hermes Agent: installs into Hermes home (%LOCALAPPDATA%\hermes on native Windows, ~/.hermes elsewhere, or HERMES_HOME), enables the plugin in config.yaml, registers plugin hooks, slash/CLI commands, skills, and writes MCP config.
CodeBuddy Code: installs a user-scope local marketplace plugin under ~/.codebuddy/memorix-local with MCP, skills, and hooks. It does not change existing CodeBuddy model, permission, or settings files; CodeBuddy keeps third-party hook approval in its own /hooks flow.
Oh-my-Pi: installs an omp.extensions package with extension hook events, a memorix command, official skills, and writes MCP config.
DeepSeek Harness: writes a Memorix @deepseek-ai/dsh-mcp-client row into $DSH_HOME/cordis.patch.yml (default ~/.dsh/cordis.patch.yml), appends guidance to the harness AGENTS.md, and installs official skills under $DSH_HOME/skills. The row follows DSH's own shipped Memorix reference, so tools appear as mcp__memorix__*.
WorkBuddy: writes a Memorix MCP server row into ~/.workbuddy/mcp.json (or <project>/.workbuddy/mcp.json for project installs) and appends guidance to AGENTS.md. Tools appear as mcp__memorix__*; there is no hooks surface.
Need a quieter install? Add --noHooks for targets where setup can control hook capture separately from the host's official package entry. It keeps MCP and guidance, but skips Memorix hook capture.
If you intentionally want repo-local guidance or hooks, run the same command inside that repository without --global.
If your agent only needs a manual MCP entry, use stdio:
{
"mcpServers": {
"memorix": {
"command": "memorix",
"args": ["serve"]
}
}
}For a manually managed Claude Code entry, add "alwaysLoad": true inside the memorix server object. This lets Claude Code expose Memorix tools during print-mode startup; memorix doctor agents --agent claude can detect and repair a missing setting.
HTTP is not required for normal setup. Use it only when you intentionally want a shared background service, dashboard, VPS Docker deployment, or multiple clients using the same endpoint. Local development uses the Node service directly and does not require Docker:
memorix background startThen point the client at:
http://localhost:3211/mcpIn HTTP mode, agents should bind the active repo explicitly with memorix_session_start(projectRoot=...) when the client can provide the workspace path. Git remains the final source of truth for project identity.
Preview what will be removed:
memorix uninstall --dry-runStop the background service and remove hooks:
memorix uninstall --background --hooksFull cleanup:
memorix uninstall --yes --background --hooks --purge-data
npm uninstall -g memorixmemorix uninstall reports MCP config entries for manual cleanup instead of silently editing every MCP file it finds.
memorix --cwd /path/to/repo resume "continue release blocker"
memorix checkpoint list
memorix memory search --query "release blocker"
memorix memory --help
# Optional: activate one local agent identity for personal/team records and coordination.
memorix identity join --agent-type codex --name codex-main
memorix memory store --text "private investigation note" --visibility personal
memorix task create --description "verify the release package"
# Deliberate durable memory: create a candidate, then review it before it can enter a Workset.
memorix memory long-term add --kind procedural --scope user --portability portable --title "Release verification preference" --text "Run focused tests and a packed-package smoke before publishing." --applicability "When publishing an npm package."
memorix memory long-term qualify --id <id> --reason "The user explicitly confirmed this preference."
memorix memory long-term approve --id <id> --reason "Reviewed for future local projects."
memorix transfer export --format json --out ./.memorix-export.json
memorix transfer import --file ./.memorix-export.json
memorix reasoning search --query "why sqlite"
memorix git-hook --force
memorix ingest log --count 20
memorix workbenchThe CLI is direct and does not depend on an MCP session. It binds to the current Git project, or to the project supplied with --cwd. Without an active identity it reads, writes, and exports project-visible memory only. Use memorix identity join or memorix identity use --agent-id <id> only when you intentionally need personal/team memory or coordinated task actions; memorix identity clear returns the terminal to project scope. --as <active-agent-id> is the one-command alternative for scripts. Both camelCase and kebab-case flags are accepted.
Media is opt-in. An explicit local import is copied into Memorix's local data directory, hashed, and kept outside the Git worktree. It becomes normal memory only when you attach it. Memorix never captures every screenshot or tool output. An asset may be up to the configured media limit (100 MiB by default). Automatic vision analysis is deliberately capped at 20 MiB; a larger image is still kept and can be attached, but Memorix records a clear text fallback instead of sending an oversized payload to a model provider.
memorix media import --path ./architecture.png --json
memorix media attach --asset <asset-id> --title "Architecture diagram" --json
memorix media list --kind image --json
memorix media show --asset <asset-id> --json
memorix media remove --asset <asset-id> --force --json
# Controlled derivations: explicit, bounded, and attachable to memory.
memorix media derive-pdf --asset <asset-id> --attach --json
memorix media derive-audio --asset <asset-id> --attach --json
# Legacy image analysis now uses the same controlled asset lifecycle.
memorix ingest image --path ./architecture.png --jsonMiniMax image generation is a deliberate CLI operation. Video generation returns a durable job immediately; inspect or cancel that job rather than waiting in an agent request.
# Configure MINIMAX_API_KEY in your user environment or .env, never in Git.
memorix media generate image --prompt "A clean system architecture diagram" --json
# Image-to-image with a reference image (MiniMax image-01 / image-01-live):
memorix media generate image --prompt "Keep the subject, change the background" --image ./reference.png --json
memorix media generate video --prompt "A short product walkthrough" --json
memorix media status --job <media-job-id> --json
memorix media cancel --job <media-job-id> --jsonmemorix_media is the compact MCP companion in every profile, including
micro. It supports import, attach, list, show, PDF/audio derivations,
generation, and job status. MCP image and video generation are disabled by
default because they may incur provider costs.
Set MEMORIX_MCP_MEDIA_GENERATION=1 only after you deliberately want an agent
to request billed MiniMax output. The normal OpenRouter text embedding lane is
still text-only; media vectors are created only by a provider that explicitly
declares support for that modality. Text descriptions and attachments remain a
useful ordinary retrieval fallback.
memorix
# or
memcodeThis opens memcode, a terminal coding agent that uses the same Memorix project memory as your MCP-connected agents.
Layer | Stores | Best for |
Observation Memory | facts, gotchas, fixes, implementation notes | "How does this work?" |
Reasoning Memory | rationale, alternatives, constraints, risks | "Why did we choose this?" |
Git Memory | commit-derived engineering facts | "What changed and where?" |
Code Memory | files, symbols, import edges, and memory-to-code freshness | "Which current code should I inspect first?" |
Curated Long-term Memory | reviewed episodic events, stable facts, or reusable procedures with evidence | "What should this agent still know or do later?" |
Compact Continuity | recent host-native compact summaries or lifecycle markers | "What survived the last context compaction?" |
Search is project-scoped by default. scope="global" searches across projects. The search boosts Git Memory for "what changed" questions and reasoning records for "why" questions.
Long-term memory is deliberately not an automatic dump of every note. A source observation, Claim, workflow, session, and code snapshot keep their existing roles. An agent may ask memorix_store to create an additional long-term record; an explicit request auto-qualifies and enters task briefs as a durable anchor, while hook-captured or Git-derived candidates stay pending until qualified. Approval stays an explicit operator review. Use memorix memory long-term approve|archive|supersede to record the evidence-backed lifecycle. Only a manually created or user-confirmed user + portable item may be considered in another local project; project code, Git facts, tests, workflows, sessions, and observations cannot be promoted into portable user memory.
memorix context "..." is the default Memory Autopilot entry. It builds a compact task-lensed brief for agents: bugfix tasks lean toward tests and repros, release tasks lean toward package/changelog/build checks, onboarding tasks lean toward docs and entry points, and stale or unrelated memories stay in warning lanes instead of flooding the prompt. Use --fallback --brief-json when MCP is unavailable and a CLI fallback needs the same bounded brief plus a receipt of what was selected or omitted; --json remains the detailed diagnostic form. A normal new task does not receive an old-session dump. For an explicit continuation, memorix resume "..." adds only the latest useful session summary, up to three readable durable anchors, and at most one recent source-labelled host compact checkpoint. A durable anchor carries a durable:<id> reference, so an agent can expand the full reviewed record through memorix_detail only when needed. Keyword matches stay primary; when no reviewed durable item matches and an embedding provider is configured, Memorix makes one 1.8-second, no-retry semantic fallback for paraphrases or cross-language tasks. A slow or unavailable provider simply leaves the normal keyword-only Workset intact. A checkpoint is lifecycle evidence, not durable memory or a transcript backup. Agents should read the suggested files before trusting stored memory.
You want | Run |
Install an agent integration package |
|
Check or repair an agent integration |
|
Manually expose stdio MCP |
|
Run shared HTTP MCP plus dashboard |
|
Debug HTTP MCP in the foreground |
|
Inspect or manage memory directly |
|
Manage reviewed long-term memory | `memorix memory long-term list |
Retire memories from retrieval |
|
Inspect native compaction continuity | `memorix checkpoint list |
Use the interactive terminal memory control plane |
|
Use the bundled terminal agent |
|
Run orchestrated subagent work |
|
memorix serve defaults to --mode micro (9 tools) to keep MCP tool schemas small for agents. memorix setup writes --mode lite (20 tools) into the installed MCP config so the normal memory and session surface is reachable. Use --mode team (28 tools) for coordination tools, or --mode full (47 tools) for advanced and compatibility tools such as checkpoint inspection.
Shortcuts and aliases: memorix search / remember / recent are direct query shortcuts, bg/bs start the background service, hook runs the hook launcher, and memorix config get|path|migrate inspects or migrates config files.
memorix orchestrate uses the current checkout for single-worker runs. When running multiple workers, it creates task worktrees under .worktrees/ and merges successful task branches back. Use --isolated to force worktree isolation for one worker, --no-worktree to disable it, --allow-dirty to run with uncommitted changes, and --no-auto-merge to preserve task worktrees for manual review.
memcode is the terminal coding agent bundled with Memorix. It can read, edit, run commands, resume sessions, switch models, and use /memory commands — all backed by the same project memory as your MCP-connected agents.
Use it when you want a terminal agent with memory already wired in.
one Git project -> one shared Memorix memory poolSee docs/MEMCODE.md for the memcode-specific guide.
Minimal ~/.memorix/config.toml:
[agent]
provider = "openai"
model = "gpt-4o"
api_key = "..."
[memory.llm]
provider = "openai"
model = "gpt-4o-mini"
api_key = "..."
[embedding]
provider = "auto"
[memory]
inject = "minimal"
formation = "active"Use [memory.llm] and [embedding] for Memorix memory quality and retrieval. Use [agent] for the model memcode talks to while coding. Keep credentials in global config or environment variables, and do not commit secrets.
For OpenRouter embeddings, use provider = "api", base_url = "https://openrouter.ai/api/v1", and model = "qwen/qwen3-embedding-8b". Memorix accepts OPENROUTER_API_KEY for that embedding endpoint; MEMORIX_EMBEDDING_API_KEY remains the explicit override.
For controlled MiniMax media generation, set MINIMAX_API_KEY (global) or
MINIMAX_CN_API_KEY (China region) in your environment or .env. The media
library never stores that key, a signed output URL, or base64 payloads. CLI
generation is explicit; MCP generation additionally requires
MEMORIX_MCP_MEDIA_GENERATION=1.
Docker is a VPS/hosted HTTP deployment option, not a requirement for local development or stdio MCP:
docker compose up --build -dThen open:
dashboard: http://localhost:3211
MCP: http://localhost:3211/mcp
health: http://localhost:3211/health
The container must be able to access the repository path passed as projectRoot for project-scoped Git and config behavior.
Use Memorix directly from TypeScript:
import { createMemoryClient } from 'memorix/sdk';
const client = await createMemoryClient({ projectRoot: '/path/to/repo' });
await client.store({
entityName: 'auth-module',
type: 'decision',
title: 'Use JWT for API auth',
narrative: 'Chose JWT because the API is stateless and used by multiple clients.',
});
const results = await client.search({ query: 'auth decision' });
await client.close();Start here | Use when |
You want the shortest route to the right guide | |
Installing, using | |
Plugin packages, MCP, project rules, hooks, and skills support | |
TOML config, model lanes, compatibility files | |
MCP tools and CLI commands | |
Commit ingestion and searchable engineering truth | |
Containerized HTTP service | |
Using the bundled terminal agent | |
AI-facing execution guide for install, binding, hooks, and troubleshooting | |
Contributing, testing, release checks | |
What changed in each release |
LLM-friendly summaries: llms.txt and llms-full.txt.
git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install
npm run lint
npm test
npm run buildMemorix draws from the MCP ecosystem and prior memory projects such as mcp-memory-service, MemCP, claude-mem, and Mem0. memcode is based on the Pi coding-agent codebase and adapts its terminal-agent model for the Memorix ecosystem.
Generated daily from GitHub stargazer events by GitHub Actions.
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 |
| refresh | No | Code Memory refresh policy. auto refreshes only when missing or stale. | auto |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It mentions 'Schedules Code Memory refresh when needed' which hints at a side effect, and lists included elements. However, it doesn't clarify whether the tool modifies anything persistent, whether it reads from disk, or what side effects scheduling refresh has. The output format is partially covered by the format parameter, but the description lacks depth on internal behavior.
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: the first states the core purpose and contents, the second gives explicit usage timing. No filler, 100% relevant information, and front-loaded with purpose.
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 5 parameters, no output schema, and no annotations, the description covers the main intended use and when to apply it. It lacks nuance about return values or potential edge cases, but given the format parameter and simple nature, it is quite complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add substantial meaning beyond the schema—it mentions 'current coding task' but doesn't elaborate on the 'task' parameter semantics. It does not describe 'agent', 'limit', 'refresh', or 'format' beyond what is in the schema, so it neither enhances nor detracts.
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: building a compact Memory Autopilot brief for the current coding task. It specifies actions (schedules refresh), content (Start here files, reliable memories, cautions), and differentiates from sibling tools like memorix_search or memorix_store by focusing on task-specific context briefs.
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 says 'Use this at the start of a new coding turn or after switching tasks,' which provides clear context for when to invoke. It doesn't explicitly mention alternatives or when not to use, but the guidance is sufficient for an agent to decide.
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.
Several tools overlap: memorix_project_context and memorix_context_pack both build context briefs, and memorix_search also retrieves relevant memories. Descriptions provide usage guidance (e.g., use project_context first, then context_pack if expanding), but an agent could still be uncertain which to invoke for a given task.
All tools share the memorix_ prefix and snake_case, but the suffix pattern is inconsistent: some are verbs (store, search, resolve), some nouns (detail, media, project_context), and some compound nouns (codegraph_status, session_start). This is readable but deviates from a strict verb_noun convention.
With 9 tools, the server is well-scoped for a coding memory system. Each tool covers a distinct functional area (store, search, retrieve, context building, session management, media) without unnecessary bloat.
Core memory operations are covered: create (store), read (search, detail), update status (resolve), and context generation. However, there is no direct edit/delete tool (only resolve to hide), and some operations like media generation and long-term candidate review are CLI-only, leaving minor gaps.
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.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Graph-native persistent memory for AI agents — 33 MCP tools, zero-LLM writes.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AVIDS2/memorix'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
