agentmemory-codex-windows
This is an AgentMemory MCP server for project-scoped memory, recall, provenance, graph curation, and workflow/action management.
Capture, search, recall, and inspect observations, durable memories, lessons, sessions, timelines, file history, patterns, profiles, and insights.
Save, verify, export, archive, restore, delete, and audit memories/lessons; manage context slots, facets, snapshots, Obsidian exports, and Claude bridge sync.
Query, upsert, reconcile, and purge entity/concept graphs with provenance, project scoping, dry-run previews, and audit reasons.
Manage actions, leases, routines, checkpoints, sentinels, sketches, signals, team sharing/feed, and peer mesh sync.
Run diagnostics/healing, consolidation/reflection/crystallization, vision search, and markdown compression.
Enforce exact-project/agent scoping, wildcard reads only, access tracking controls, and safety checks for destructive or write operations.
Provides memory and context persistence for OpenAI Codex, capturing user prompts and assistant responses to preserve useful context across coding tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@agentmemory-codex-windows recall what we discussed about the deployment issue last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AgentMemory for Codex on Windows
Published preview.19/r269. The fixed Release contains four assets whose public downloads were verified by size and SHA-256. Payload build source:
7e66cd75702222aece989ac1c6be4c73aa004e7d; tag source:0d9ec592c127eb4c93479452d191b67b0baf3576with successful Windows CI. This subsequent documentation-only main update and its own CI are separate; see the Release for the separate follow-up commit and CI status. The frozen tag and payload are not rebuilt.
Historical preview.18/r225: The fixed Release provides the four verified assets, hashes and installation instructions. Tagged public source:
6359546a; payload workspace source:3632849b. This post-publication main documentation and its CI are separate from the unchanged binary build source. Historical preview.17/r216 remains preserved.
Independent, Windows-native AgentMemory downstream for OpenAI Codex Desktop and Codex CLI.
Install without building · Operating guide · Validation and limits · Release notes
This is an independent Technical Preview. It is based onAgentMemory v0.9.30, but it is
not the official upstream repository, an @agentmemory/* npm release, or a
promise of upstream support. Do not use an upstream npx command or the
compatibility plugin manifests as a substitute for the Windows build and
installer described here.
Development note: this downstream is AI-generated and user-tested; read the full disclosure.
Published preview.19 / r269
The fixed Release supplies the matched ZIP, TGZ launcher, descriptor and checksums. Compatibility remains AgentMemory 0.9.30 / engine and SDK 0.22.1 / data contract 5. See changes, installation, update, recovery and bounded qualification. Historical preview.18 and earlier tags/assets remain unchanged.
Related MCP server: RepoRecall
Start here
The preview.19 release line packages AgentMemory 0.9.30 with the downstream-patched iii engine/SDK 0.22.1. The same installer supports an empty target, an owned managed installation, or an explicitly identified original upstream 0.9.29/0.9.30 file-backed installation. You do not need to install upstream first.
Preview.19 is the published r269 Windows technical preview. The fixed Release records exact source identities, successful CI, download hashes and limits. Use only its matching launcher and ZIP; previous releases retain their own guides.
Check Windows x64, Node.js 24+, Windows PowerShell 5.1 and Codex desktop, then follow the pinned installer guide. The published release includes a prebuilt runtime; source builds are optional.
Preview the selected installation path, then use
--execute. For an empty target the default path prepares, activates and validates the service;--freshand--activate-preparedremain available for separate phases. Connect Codex MCP after service validation.If a step fails, use support and recovery guidance. Report the release and failing phase with a short redacted error; do not attach memory databases or credentials.
What this preview does
AgentMemory preserves useful context across Codex tasks while keeping the official AgentMemory memory, lesson, graph, audit, and provenance stores as the only canonical stores.
Captures normal main-agent user prompts and final assistant responses through four managed Codex hooks:
SessionStart,UserPromptSubmit,Stop, andSessionEnd.Excludes ambient UI, title/fork traffic, known internal host prompts, and subagent traffic from durable capture.
Keeps writes, deletion, curation, and provenance exact-project scoped.
Supports audited, target-scoped live graph provenance correction with dry-run previews. Manual graph writes with multiple source groups must map every node and edge through zero-based
sourceIndexes, or explicitly opt into shared provenance withsharedSources: true.Supports audited recovery of proven empty observations through the existing REST forget endpoint, with exact IDs, version checks and preserved graph cursors.
Supports bounded, source-labelled federated recall across projects without allowing wildcard writes.
Can use a credential-free, loopback-only local Qwen worker for typed graph extraction. Every other AgentMemory LLM feature receives the noop provider; external fallbacks remain disabled.
Uses an authenticated loopback MCP endpoint for Codex and retains a packaged stdio launcher only as a compatibility path.
The upstream-compatible source surface contains 58 MCP tools. Its MCP surface is 58 tools, 6 resources, and 3 prompts; it also has 143 endpoints on port 3111, 12 portable hooks, and 17 skills. The supported Windows profile intentionally activates only the four managed hooks listed above.
For audits, MCP memory_recall, memory_smart_search, and memory_timeline
accept trackAccess: false to avoid access-count reinforcement. The default
remains true; visibility, project boundaries, and recovery guards still apply.
Graph query shards are rebuildable indexes in the same iii StateModule as the
canonical graph. Missing or dirty indexes use a bounded snapshot with a warning;
only an explicit snapshot rebuild refreshes them.
Release changes are recorded in CHANGELOG.md. Source tags identify public releases; each build manifest records its own qualification.
Historical changes in preview.18
Resume native capture across structurally validated
additional_toolsdeclarations; preserve conservative stops for unknown or malformed content.Serialize Qwen lease lifecycle across processes, verify process-start identity and honor foreground ownership.
Remove development-only pnpm metadata from installed runtime inputs.
Carry the earlier bounded decompression/correspondence and evidence-bound distribution fixes. See qualification, installation/update/removal/recovery and limits. The r223 baseline and new package qualification are reported separately.
Changes in preview.16
Keeps memory replacement, slot updates, import and deletion within the exact project and agent owner, including partial acknowledgements and concurrent capture.
Applies archive and pending-import visibility before recent-result limits; shows derived session summaries only while their canonical source digest still matches.
Uses last activity to distinguish a long active session from an idle abandoned session.
Records E2E write intent before dispatch and requires actual server completion before cleanup; request headers, body failures and parse failures have distinct outcomes.
Adds successful installation backup closeout and bounded synthetic qualification without starting general LLM features.
Final package qualification is recorded in the release notes. Earlier installation evidence remains labelled with its original revision.
Changes in preview.15
Integrates upstream AgentMemory 0.9.30 while preserving canonical source text, exact-project filtering and graph provenance.
Uses one installer for new installations, managed updates and qualified original upstream adoption; newer unsupported upstream versions are retained rather than silently downgraded.
Pins iii 0.22.1 with the file flush barrier and bounded state/stream pagination. Acknowledged managed writes wait for the barrier; process-crash qualification does not certify power-loss recovery.
Settles deliberately skipped captures without false dead letters and distinguishes graph-provider availability from intentionally disabled general LLM features.
Removes each successful build invocation's own disposable scratch unit; failures remain available for diagnosis. Shared caches, release packages and canonical data are separate.
See release notes for verification scope and retained limitations.
How search, filtering, and indexes work
Normal recall searches stored observations and reusable lessons. Keyword retrieval uses BM25 with Korean inflection and literal identifier handling. Where available, vector and stored-graph candidates join the same ranked result set. A graph search reads existing nodes, edges, and source references; it does not ask local Qwen to answer the query. Qwen is used separately for background graph extraction in the supported Windows profile.
Search candidates are checked against their canonical observation and session.
Project, speaker, archive, and ambient-source eligibility apply before selecting
the returned result count. Literal code and quoted source text are preserved;
ambient-looking text inside those regions is not automatically discarded. Use
memory_smart_search for compact candidates, then expandIds to inspect the
original observations and their provenance. Use an exact registered project ID;
* is an intentional federated read, not permission for cross-project writes.
The keyword snapshot and graph-query shards are rebuildable derived indexes. Compacting the keyword representation does not delete conversations, change observation IDs, or remove their canonical source text. Preview.13 reduced the measured keyword snapshot text size by 63.6% with preserved posting order and scores. Graph output is also derived: verify consequential conclusions against source observations rather than treating an extracted relationship as a fact.
Preview.14 fixes multi-seed graph retrieval: when several matched entities or source chunks reach the same observation, the strongest candidate wins together with its context and provenance. A weak path discovered first can no longer hide a later direct match. Expansion continues excluding the input observations, and existing project and source-visibility checks remain in place.
Validation scope and known limitations
The existing checks cover package behavior, managed hooks, capture/filtering, authenticated MCP/REST, graph provenance, installer/recovery, and packaged CLI/MCP entrypoints. Regression tests exercise connected graph seeds in both orders, stronger direct matches, shorter expansion paths, provenance replacement, and result limits. The fixed live historical set contains 50 questions with original observation IDs; it measures retrieval on the installed runtime rather than assuming that unit tests prove live success. Exact release results are published in the release notes.
A preview.13 investigation reproduced an intermittent roughly six-second caller response. Native MCP completion took about 1.4 seconds; roughly 4.5 seconds followed that completion before the calling script resumed. The precise post-completion cause and any influence from concurrent conversations remain unknown. Qwen inference is not part of that search path. The graph-ranking fix is a separate confirmed defect and is not presented as a fix for this intermittent delay.
AdGuard/redirect-driver interoperability remains unqualified. Validation on one Windows/Codex host is not certification of every host configuration or every upstream-compatible operation. The binaries remain unsigned; SHA-256 checks verify artifact integrity, not publisher signing. See the installation guide for preparation, activation, update, data preservation, and rollback boundaries.
When the graph updates
The managed hooks store eligible conversation turns as observations. A new committed observation wakes the existing graph backlog scheduler; rejected or duplicate observations do not. A wake failure leaves the observation intact.
The current Codex model selects reusable decisions and verified fixes through official memory, lesson, and graph curation tools with source provenance. Storing a final answer alone does not mark it as a verified decision.
If the optional local Qwen graph provider is configured and available, the scheduler enriches the graph in bounded batches. Runtime readiness must be stable for 15 seconds; an observation wake reuses an already stable runtime without restarting that wait. Drains run up to four batches, with a 30-second cooldown before continuing full drains. A 15-minute probe covers missed wakes and restarts. Foreground Qwen work can defer extraction without advancing the cursor.
The Windows adapter now requests conditional Qwen startup automatically when the configured provider is unavailable and the existing backlog selector finds processable observations. It uses the workspace's existing LocalAI launcher; manual holds, GPU/RAM admission and shared-consumer protection stay with that launcher. Failed admission is retried on the 15-minute recovery cycle. Only an instance started by this worker is released after five minutes of empty backlog. No LocalAI installation or universal memory threshold is bundled. Hosts without that integration continue using an already running provider. Provider-free manual curation and deterministic structural extraction remain available.
See the operating guide for readiness coordination, cursor recovery, and provider limits.
Version identities
Identity | Value | Meaning |
Downstream release |
| Versioned source tag and pinned installer distribution |
AgentMemory compatibility |
| CLI, MCP, package, API, export, and installed-runtime compatibility |
Qualification revision | Build manifest | Internal build provenance, not a public version line |
iii engine |
| Pinned patched native runtime input, verified by SHA-256 during the build |
The exact upstream tag, commit, tree, and pristine package hash are recorded in
upstream-source.json.
Install without building
Use the matching preview.19 GitHub release ZIP or version-pinned TGZ launcher with the pinned npm/npx installation guide. It covers automatic empty-root installation, optional separate preparation/activation, managed updates, original upstream adoption, and offline hash verification. The GitHub TGZ can be run with npm without a separate npm-registry publication. Users need Windows x64, Node.js 24+, and Codex; pnpm, Python, and compilers are only needed by source builders.
npm 12 blocks remote TGZ packages by default. The installer command includes
--allow-remote=root for the explicitly selected launcher; it does not change
global npm settings. See the npm policy.
Source-build requirements
Windows with PowerShell 5.1 or newer; this preview is qualified on Windows 11
Node.js 24 or newer
Python 3 on PATH for the plaintext HTTP regression tests (CI uses Python 3.12)
pnpm
11.25.0through the repository's pinned package-manager declarationThe pinned downstream-patched iii engine
0.22.1Windows executable whose SHA-256 matchespackaging/windows-codex/config/third-party-inputs.json
The npm launcher uses a prebuilt release ZIP. The binaries are not Authenticode-signed; the pinned npm descriptor, ZIP SHA-256 and per-file manifest provide integrity checks.
Build and evaluate from source
Use the published version-tag checkout on Windows, then run the release builder from PowerShell. The output directory must not already exist.
git clone --branch v0.1.0-preview.19 https://github.com/M-T-D-N/agentmemory-codex-windows.git
Set-Location agentmemory-codex-windows
& .\packaging\windows-codex\Build-WindowsCodex.ps1 `
-OutputDirectory D:\staging\agentmemory-codex `
-IiiEnginePath D:\inputs\iii-0.22.1.exe `
-ScratchDirectory D:\staging\agentmemory-build-temp `
-ReleaseRevision r199The normal builder verifies the pinned native input, restores the frozen lock, checks generated skills, type-checks, builds, runs the package and Codex adapter tests, creates a production dependency tree, and writes a complete immutable file manifest.
The installer is dry-run by default. It validates release hashes, ownership,
paths, and the existing installation before changing anything. Review the exact
build, dry-run, cutover, rollback, retention, and authentication contract in
packaging/windows-codex/README.md before
using -Execute.
The Windows installer is designed for an owned, managed AgentMemoryCodex
service layout. Do not point it at an unrelated directory or treat build
output as user data. Canonicaldata, secrets, logs, task identity, and
rollback state have independent lifecycles.
Updating an existing installation
Check out the release tag into a source checkout and use a fresh staging directory.
Choose a new -ReleaseRevision rN that is not already installed; r83 in the
examples is a build label, not permission to overwrite an existing r83 runtime.
Run the installer dry-run against the same owned installation, review the exact
predecessor and target, and follow the approved cutover and rollback procedure.
Canonical data, secrets, and instance metadata stay in the installation. Do not
copy data into the source tree or invoke the historical one-off session-stub
migrations removed from this preview. See the agent runbook.
Privacy and security boundaries
MCP and service traffic stay on authenticated loopback endpoints in the supported profile.
The optional Qwen provider accepts only credential-free loopback HTTP and is capability-scoped to graph extraction.
The source tree contains no operating memory database, actual user transcript or user export, API key, generated installer, or private development history.
Security reports should use GitHub's private vulnerability reporting flow; see
SECURITY.md.
Repository map
Path | Purpose |
| AgentMemory compatibility source |
| Supported Windows/Codex adapter, builder, installer, and tests |
| Upstream-compatible plugin assets bundled into the source build; not the supported installation path |
| Unit and security regression tests |
| Upstream-derived harnesses and historical reference results; not Windows preview qualification |
| Compatibility integrations; not separately supported downstream products |
| Exact upstream provenance |
The upstream marketing website, cloud deployment configurations, other upstream language copies, generated build output, and private monorepo history remain outside this public snapshot. Four cloud entrypoint source files are retained only because the normal Windows packaging suite directly tests their secret-output behavior; they do not add cloud support. Historical benchmark material is retained only for reproducibility and is explicitly labelled as upstream reference; no benchmark number in those directories is a claim for this downstream preview.
Development checks
pnpm install --frozen-lockfile
pnpm run skills:check
pnpm run typecheck
pnpm run build
pnpm testFor Windows adapter and packaging checks, use the
agent runbook's source-check procedure.
It reads the current adapter/packaging lists from test-suites.json, keeps
integration/curation disabled, and uses an explicit synthetic scratch directory.
The repository is marked private in package manifests to prevent accidental
publication under upstream @agentmemory/* package names. Contributions should
follow CONTRIBUTING.md, and the downstream release history
is in CHANGELOG.md.
AI development disclosure
Most downstream modifications were generated and revised by OpenAI Codex from user-provided requirements and iterative acceptance requests. The repository owner did not manually review the source code. Validation is based on automated tests and live functional testing in the owner's Windows/Codex environment. No independent third-party code or security audit has been performed.
In short: AI-generated, user-tested, not manually code-reviewed.
Upstream attribution and license
This downstream is based on AgentMemory by Rohit Ghumare and contributors. See
NOTICE and upstream-source.json for the
attribution and exact source identity. The code is provided under the
Apache License 2.0.
Available Tools
58 toolsmemory_action_createA
Persist a work item and optional dependency edges, returning {success,action,edges}. title is required; parentId and comma-separated requires IDs must name existing actions. Any requires edge creates the action as blocked; otherwise it starts pending. Priority defaults to five and is clamped to 1-10. Each call creates a new action and audit entry. Use memory_action_update for an existing action or memory_routine_run for a stored workflow.
Inputs: title (required), tags, project, parentId, +3 more.
memory_action_updateA
Change an existing action's status, result or priority, returning the updated action and recording an audit entry. status='done' can return blocked dependents to pending when their required actions are done; this propagation does not recheck checkpoint gates. Missing actions return an error; priority is clamped to 1-10. Use memory_action_create for new work and memory_lease to claim execution rather than merely changing status.
Inputs: actionId (required), result, status, priority.
memory_archiveA
Inspect/list reversible archive state, review current retention/TTL candidates, or preview/apply archive and restore in an exact project. Originals, IDs and provenance remain in canonical storage. Default action is inspect; archive/restore default to dry-run. Apply requires the preview revision, digest and a reason. Candidate listing is read-only and requires individual review. This does not enable automatic retention or perform forget.
Inputs: project (required), limit, state, action, +8 more.
memory_auditA
Inspect recorded memory operations to explain a change or verify its history. Returns audit entries newest first, optionally filtered by exact operation name; limit defaults to 50. Entries include timestamps, affected IDs and operation details. This queries existing audit records rather than checking subsystem health; use memory_diagnose for current consistency checks. Query failures return an error result.
Inputs: limit, operation.
memory_checkpointA
Manage a recorded external gate rather than performing a CI, approval or deploy check itself. operation='create' requires name and optionally gates existing linkedActionIds; 'resolve' requires checkpointId and passed/failed status. Passing can unblock actions when all requirements/gates are met; resolving a non-pending checkpoint fails. 'list' reads stored checkpoints. Returns checkpoint and unblock count, or a checkpoint list. Create/resolve persist state and audit entries; use sentinels for event-driven conditions.
Inputs: operation (required), name, type, status, +2 more.
memory_claude_bridge_syncA
Exchange data with the configured Claude Code MEMORY.md bridge. direction='read' reads and parses the file, storing a last-read snapshot and audit entry; it does not create durable memories. direction='write' overwrites MEMORY.md with visible latest memories under the configured line budget and returns its path and line count. Requires an enabled bridge and configured file path. Use memory_export for a complete JSON backup.
Inputs: direction (required).
memory_commit_lookupA
Read the stored commit/session link for one full git commit SHA. Returns {commit,sessions}, where commit contains recorded metadata and visible sessionIds, and sessions contains their stored session records. Missing or excluded ambient sessions are omitted. An unrecorded SHA returns {commit:null,sessions:[]}; a missing or empty sha returns an error. This read does not scan Git repositories or prove who authored a commit. Use memory_commits to discover recorded links by branch or remote repo URL, or memory_timeline to read a linked session's observations.
Inputs: sha (required).
memory_commitsA
List recorded Git commit/session links, newest linkedAt first, with optional exact branch and remote repo URL filters. Returns {commits}; limit defaults to 100 and is capped at 500. Excluded ambient sessions are removed from session links. This queries stored links rather than scanning Git repositories. Use memory_commit_lookup when you already know a commit SHA.
Inputs: repo, limit, branch.
memory_compress_fileA
Shorten prose in an existing .md file using the configured LLM, validating that headings, URLs and fenced code blocks survive. Requires an enabled LLM provider; noop mode returns disabled. Rejects symlinks and sensitive-looking paths. After validation, writes a sibling backup, normally .original.md (overwriting an existing backup), and replaces the source. Returns source/backup paths and character counts, or a validation/error result. Use for file compression, not durable memory consolidation.
Inputs: filePath (required).
memory_consolidateA
Run the configured LLM-backed consolidation pipeline, mutating stored semantic/procedural memory, reflection insights and decay strengths with an audit entry. Omit tier for all, or select semantic, reflect, procedural or decay; episodic is not implemented. This tool exposes no project filter. Returns {success:true,results} with per-tier counts, skipped reasons or errors; success:true can include tier failures. Semantic needs at least 5 summaries, procedural at least 2 recurring patterns. Disabled configuration returns {success:false,skipped:true,reason}; the MCP handler reports this or a thrown pipeline failure as unavailable. Optional OBSIDIAN_AUTO_EXPORT also writes an export. Disabled by default in zero-LLM/noop and managed local-qwen modes; use memory_save, memory_lesson_save or memory_graph_upsert for curated writes.
Inputs: tier.
memory_crystallizeA
Summarize the specified done or cancelled actions and their links using the configured LLM. Stores a crystal digest, attempts to save extracted lessons and links source actions to the crystal; returns {success,crystal}. Missing or unfinished action IDs fail. actionIds is comma-separated; project/sessionId annotate the digest. Use for a completed work chain, not general recall; zero-LLM workflows should save curated lessons directly with memory_lesson_save.
Inputs: actionIds (required), project, sessionId.
memory_diagnoseA
Inspect current subsystem consistency, returning {success,checks,summary} with pass/warn/fail and fixable counts. categories is comma-separated; omission checks all supported categories, and unknown names are ignored. Checks cover action dependencies, leases, sentinels, sketches, signals, sessions, memory and derived data, and mesh state. Does not apply repairs. Review the findings before using memory_heal; use memory_audit for historical operations.
Inputs: categories.
memory_exportA
Return a versioned JSON export of stored AgentMemory data, including sessions, observations, memories, graph and derived collections. Use for backup or transfer; this tool returns data rather than writing an export file. It has no project filter and may expose a large cross-project payload. Oversized responses report a transport-limit error. Use memory_obsidian_export for Markdown files or memory_snapshot_create for a local Git snapshot.
Inputs: no named parameters.
memory_facet_queryA
Find IDs categorized by stored dimension:value facets. Supply at least one comma-separated matchAll (AND) or matchAny (OR) list; when both are present, both conditions must pass. targetType optionally narrows action, memory or observation matches. Returns up to 50 results with targetId, targetType and matchedFacets, not full target records. Use memory_facet_tag to add facets or memory_recall for content-based retrieval.
Inputs: matchAll, matchAny, targetType.
memory_facet_tagA
Store a dimension:value facet on an action, memory or observation ID for later filtering with memory_facet_query. Returns {success,facet}; a matching targetId/dimension/value already present returns skipped:true without adding another facet. dimension and value must be nonempty. This stores categorization metadata and does not update the target's content or status; use memory_action_update to change an action's state.
Inputs: value (required), targetId (required), dimension (required), targetType (required).
memory_file_historyA
Retrieve context for comma-separated file paths before editing or investigating them. Searches up to 15 recent visible sessions and includes up to five important observations per file; sessionId excludes the current session. Omit project or use '*' to search across projects. Returns a context string containing an agentmemory-file-context block, or an empty string. Matching observations record retention access; use memory_recall for general topic searches.
Inputs: files (required), agentId, project, sessionId.
memory_frontierA
Rank unfinished actions with no detected dependency, checkpoint or active-conflict blockers. Returns frontier items with action, score and lease state, plus totalActions and totalUnblocked; project filters the set. Supply agentId to exclude actions leased by others. This suggests candidates without acquiring leases or changing status. Use memory_next for a single suggestion and memory_lease to claim an action.
Inputs: limit, agentId, project.
memory_governance_deleteA
Permanently delete the comma-separated memoryIds and their access/search-index entries, recording an audit reason. Use memory_archive for reversible hiding. Supply the exact project for archived targets; when supplied, every selected existing memory must belong to it. Deleted originals' archive metadata is removed. Returns success, deleted count and requested total, plus archiveStatesRemoved when applicable; missing IDs are skipped. This does not delete sessions or observations.
Inputs: memoryIds (required), reason, project.
memory_graph_provenance_reconcileA
Correct exact graph targets in one project with a required audit reason and validated session/observation sources. action defaults to detach: remove selected node/edge source references while retaining a final source observation. retire/restore changes only exact edge visibility, preserves original provenance and edge history, and requires expectedUpdatedAt plus canonical review evidence in sources. restore also requires live same-project endpoints and valid original provenance. dryRun:true previews without mutation; otherwise changed targets update graph/index state and create an audit entry. Returns {success,action,project,dryRun,changedTargets,results} with per-target before/after provenance and removed IDs; applied changes also return auditId. Unchanged targets have changed:false. Invalid, missing, stale, wrong-project or conflicting targets return {success:false,error}. Use memory_graph_query to inspect targets and memory_graph_upsert to add supported relationships; memory_graph_purge physically deletes a project graph.
Inputs: reason (required), project (required), targets (required), action, +1 more.
memory_graph_purgeA
Irreversibly purge graph records for one exact project with a required audit reason. First obtain the complete live nodeIds/edgeIds inventory using memory_graph_query; a clean snapshot covering at most 500 nodes and 1000 edges across the graph is required. Inventories must match exactly; an empty project, partial/dirty/reset snapshot, changed records or oversized physical project fails with {success:false,error}. There is no dry run. Deletes project nodes including stale rows, incident/project edges, their edge history, indexes and archive metadata; preserves sessions, observations, memories and lessons. Returns {success,project,auditId,nodesDeleted,edgesDeleted,liveNodesDeleted,liveEdgesDeleted,archiveStatesRemoved,nodeIds,edgeIds,remainingNodes,remainingEdges}. Physical counts may exceed supplied live counts. Use memory_graph_provenance_reconcile for selective provenance correction or reversible edge retirement.
Inputs: reason (required), edgeIds (required), nodeIds (required), project (required).
memory_graph_queryA
Read stored entity/concept graph nodes and edges in an explicit project, or '*' for deliberate cross-project reads; no automatic extraction is required. startNodeId selects bounded traversal, while query and nodeType filter nodes. Returns nodes, page-local edges, depth, totals and pagination/truncation metadata. edgeLimit/edgeOffset opt into an independent exact edge inventory page. Inspect warnings and totalsExact before treating totals as complete. Use memory_relations for memory-to-memory links.
Inputs: project (required), limit, query, offset, +5 more.
memory_graph_upsertA
Create or merge manually authored graph nodes and edges in an exact project without an LLM. Official session/observation sources must belong to that project. Node keys are request-local edge endpoints; sourceIndexes selects supporting source groups, or sharedSources=true explicitly shares all groups. existingNodeId targets one validated live node. Writes provenance and audit records; returns node-key-to-ID mappings and node/edge created/merged counts. Use memory_graph_query to inspect existing graph records first.
Inputs: nodes (required), project (required), sources (required), edges, +1 more.
memory_healA
Apply supported repairs for selected diagnostic categories: action dependency state, expired/orphaned leases, sentinels, sketch actions, signals and superseded memories. This can delete orphaned or expired records and changes state with audit entries. dryRun='true' reports proposed fixes without applying them; default applies repairs. Returns {success,fixed,skipped,details}. Run memory_diagnose first and review which issues are fixable; not every diagnostic has an automatic repair.
Inputs: dryRun, categories.
memory_insight_listA
Read existing synthesized insights, excluding deleted entries and filtering by optional exact project and minConfidence. Returns {success,insights}, highest confidence first and bounded by limit (default 50). Omitted project lists insights across projects. This does not generate new insights; use memory_reflect for LLM synthesis or memory_lesson_recall for learned procedures and lessons.
Inputs: limit, project, minConfidence.
memory_leaseA
Acquire, renew or release an action lease for agentId. Acquire requires an unfinished, unblocked action and marks it active/assigned; another holder returns a conflict. Renew requires this agent's live lease. Release with a nonempty result marks the assigned action done; otherwise it returns to pending. Release does not propagate dependent completion; use memory_action_update for that transition. Writes lease/action/audit state and returns lease details or released:true.
Inputs: agentId (required), actionId (required), operation (required), ttlMs, +1 more.
memory_lesson_deleteA
Soft-delete a lesson by id. Deleted lessons are excluded from recall and list; re-saving the same content creates a fresh lesson.
Inputs: lessonId (required), project.
memory_lesson_recallA
Search saved lessons by keywords in an explicit project; '*' deliberately searches across projects. Excludes deleted/archived lessons and those below minConfidence. Returns {success,lessons} with scores ranked by relevance, confidence and recency, bounded by limit. It retrieves existing lessons without generating or reinforcing them. Use before choosing an approach; memory_recall also searches ordinary observations and durable memories.
Inputs: query (required), project (required), limit, minConfidence.
memory_lesson_saveA
Persist a reusable lesson in an exact project with context, confidence and optional official observation provenance. sources pairs are preferred; sourceIds supplies comma-separated observation IDs, all validated in that project. Matching normalized content strengthens the existing lesson and merges support/tags; otherwise creates one. Returns {success,action,lesson}, with action created or strengthened. Use memory_save for decisions/preferences, and memory_lesson_recall before applying earlier lessons.
Inputs: content (required), project (required), tags, context, +3 more.
memory_mesh_syncA
Exchange configured shared collections with registered peer AgentMemory instances. Requires AGENTMEMORY_SECRET and reachable permitted peer URLs. peerId selects one peer; omission selects all, with direction push, pull or both (default both). Push sends local data; pull merges received records. Updates local peer/audit state and returns per-peer pushed/pulled counts and errors, even when some peers fail. Use only for authorized peer transfers.
Inputs: peerId, direction.
memory_nextA
Suggest the highest-ranked action from memory_frontier for the optional project and agentId. Returns suggestion with action ID, title, priority and score plus counts, or suggestion:null when no actionable work is found. Supplying agentId accounts for leases held by other agents. It does not claim the action or start work; use memory_lease to acquire it, or memory_frontier to compare several candidates.
Inputs: agentId, project.
memory_obsidian_exportA
Write Obsidian Markdown notes and MOC.md for selected memories, lessons, crystals and sessions, with frontmatter and wikilinks. types is comma-separated; omission exports all four collections. vaultDir must stay under AGENTMEMORY_EXPORT_ROOT (default ~/.agentmemory). Creates directories and overwrites matching generated filenames; records an audit entry. Returns per-type exported counts, vaultDir and any per-file errors. Use memory_export for returned JSON instead of filesystem output.
Inputs: types, vaultDir.
memory_patternsA
Detect repeated file co-changes and error titles in visible, non-archived session observations without an LLM. File pairs need at least three sessions; error titles need at least two occurrences. Returns up to 20 frequency-ranked patterns with type, description, files, frequency and source session IDs. Omit project or use '*' for all projects; agentId preserves the configured read scope. Use memory_profile for a project overview or memory_reflect to create synthesized insights.
Inputs: agentId, project.
memory_profileA
Get a project overview from its 20 most recent visible sessions: top concepts/files, conventions, errors and recent activity. Returns {profile,cached}, or {profile:null,reason:'no_sessions'}. A current cache is reused for up to one hour; refresh='true' forces recomputation. Recomputing persists the profile cache and an audit entry. Supply the exact project identifier; agentId preserves configured scope. Use memory_patterns to inspect recurring co-changes or errors.
Inputs: project (required), agentId, refresh.
memory_recallA
Search project-scoped observations and durable memories before continuing work or checking earlier decisions. Returns ranked results in full or compact form, or narrative text; token_budget can truncate the response. sourceKind filters original user or assistant observations. Use '*' only for deliberate cross-project discovery. Returned items record retention access by default; set trackAccess=false for analysis. Use memory_smart_search for compact search followed by ID expansion.
Inputs: query (required), project (required), limit, format, +4 more.
memory_reflectA
Synthesize new insights or reinforce existing ones from project concept clusters using an enabled LLM. Requires an exact project and rejects '*' or noop-provider mode. Uses stored graph clusters or a similarity fallback over facts/lessons; persists insights and audit state. Returns newInsights, reinforced, clustersProcessed, clustersSkipped and usedFallback. Use memory_insight_list to read existing insights or memory_patterns for deterministic recurring file/error patterns.
Inputs: project (required), maxClusters.
memory_relationsA
Follow stored memory-to-memory relations, related IDs, supersession and parent links from memoryId. Returns confidence-ranked results containing memory, hop and confidence; the starting memory is excluded. maxHops defaults to two and is capped at five, with at most 500 visited memories. Returned memories record retention access. Use memory_graph_query for the separate entity/concept graph rather than memory relationships.
Inputs: memoryId (required), maxHops, minConfidence.
memory_routine_runA
Start a new run of an existing routineId, creating an action for each stored workflow step and requires edges between dependent steps. Returns {success,run,actionsCreated}; missing routines return an error. project supplies context for created actions and initiatedBy records the initiator. Each call creates a fresh run and audit entry; it does not execute the work. Use memory_action_create for a single work item.
Inputs: routineId (required), project, initiatedBy.
memory_saveA
Persist a verified insight, decision or preference in an exact project; '*' is rejected for writes. Optional sourceObservationIds must resolve to official observations in that project. Similar content may supersede an existing memory, so repeated calls can create new versions. Returns the saved memory and, when present, an advisory similarTo match. Use memory_lesson_save for reusable lessons with confidence and reinforcement.
Inputs: content (required), project (required), type, files, +3 more.
memory_sentinel_createA
Persist a watching sentinel and optional gates on existing linkedActionIds. Supply config as JSON: timer needs positive durationMs; threshold needs metric, operator gt/lt/eq and numeric value; pattern needs a pattern string; webhook needs a path. Timers schedule a local callback; other types rely on checks or external triggering. Returns {success,sentinel} and records audit state. Use memory_checkpoint for a manually resolved external gate.
Inputs: name (required), type (required), config, expiresInMs, +1 more.
memory_sentinel_triggerA
Fire an existing watching sentinel by ID, optionally attaching a JSON result payload. Stores triggered status/time, records an audit entry and can return linked blocked actions to pending when their gates pass; this does not recheck required action dependencies. Returns {success,sentinel,unblockedCount}; missing or non-watching sentinels return an error. Use memory_sentinel_create to register a condition or memory_checkpoint to resolve a recorded external check.
Inputs: sentinelId (required), result.
memory_sessionsA
Read stored session metadata in an explicit project, newest startedAt first. Returns {sessions,total,limit,offset,nextOffset}; no matches returns an empty sessions array and nextOffset:null. limit defaults to 20 (max 500); follow nextOffset with offset to continue. sessionId selects one session; agentId defaults to configured read scope and '' reads across agents. project:'' permits a deliberate cross-project read. Archived and excluded ambient sessions are hidden; includeExcluded:true requires exact project and sessionId and still hides archived sessions. Invalid filters return an error. Use memory_timeline for observations within a session.
Inputs: project (required), limit, offset, agentId, +2 more.
memory_signal_readA
Read non-expired signals visible to agentId, newest first, returning {success,signals}. threadId narrows a conversation; unreadOnly='true' selects unread messages addressed directly to this agent, excluding broadcasts. Returned unread direct messages are marked read and audited; sent messages and broadcasts are visible in ordinary reads. limit defaults to 50. Use memory_signal_send to create a message.
Inputs: agentId (required), limit, threadId, unreadOnly.
memory_signal_sendA
Store a typed message for another AgentMemory agent, or broadcast by omitting to, returning {success,signal}. Requires nonempty from and content. replyTo reuses an existing parent signal's thread when found; otherwise a new thread is created. Writes message and audit state. This MCP surface exposes no TTL parameter. Use memory_signal_read to retrieve messages; sending requires authorization for the recipient and content.
Inputs: from (required), content (required), to, type, +1 more.
memory_sketch_createA
Create an ephemeral action graph for exploratory work. Auto-expires after TTL. Can be promoted to permanent actions or discarded.
Inputs: title (required), project, description, expiresInMs.
memory_sketch_promoteA
Promote the existing actions of an active sketchId into regular work items by removing their sketch association; optional project changes their project. Marks the sketch promoted and records audit entries, returning {success,promotedIds}. Missing or non-active sketches fail. An empty sketch promotes no actions. Use after exploratory work is accepted; memory_action_create directly creates regular work items.
Inputs: sketchId (required), project.
memory_slot_appendA
Append text to an existing effective slot, inserting a newline when needed, and record an audit entry. Returns the updated slot and size, or success:false for a missing/read-only slot or sizeLimit overflow. Overflow leaves the content unchanged; use memory_slot_replace to compact it first. Project slots shadow global slots with the same label. Repeated calls append again; use memory_slot_create when the label does not exist.
Inputs: text (required), label (required).
memory_slot_createA
Persist a new size-limited context slot, returning {success,slot}. label is lowercase, starts with a letter, uses letters/digits/underscores and is at most 64 characters. sizeLimit is an integer from 1 to 20000; content must fit. Rejects duplicate labels within the selected scope; a project slot can shadow a global one. Pinned slots participate in context injection. Use memory_slot_replace for existing content; creation records an audit entry.
Inputs: label (required), scope, pinned, content, +2 more.
memory_slot_deleteA
Delete the effective slot and record an audit entry, returning {success:true}. Missing or read-only slots fail; seeded default slots are deletable when writable. With duplicate labels, deletes the project slot first, revealing the global slot on later reads. This removes the context unit rather than clearing its content; use memory_slot_replace with empty content to retain it.
Inputs: label (required).
memory_slot_getA
Read the effective slot named by label, returning {success,slot,scope} with its content and metadata. A project-scope slot takes precedence over a global slot with the same label. Invalid labels or missing slots return success:false. Use memory_slot_list to discover labels, and memory_slot_replace or memory_slot_append to edit the retrieved context unit.
Inputs: label (required).
memory_slot_listA
List effective editable memory slots, sorted by label, returning {success,slots} with content, size limits, pinning and scope. Project-scope slots shadow global slots with the same label; unpinned and empty slots are included. Use to inspect current context before creating or editing a slot, or memory_slot_get when you know its label. Slots are fixed-size context units rather than relevance-ranked memories.
Inputs: no named parameters.
memory_slot_replaceA
Replace the complete content of an existing effective slot, preserving its metadata and size limit. Empty content clears the slot. Returns {success,slot,size}; missing/read-only slots or oversized content fail without replacement. Project slots take precedence over global slots with the same label. Records an audit entry. Use memory_slot_append to add text or memory_slot_create for a new label.
Inputs: label (required), content (required).
memory_smart_searchA
Search an explicit project with hybrid keyword/semantic ranking, returning compact results with observation IDs for progressive disclosure. Supply comma-separated expandIds to retrieve up to 20 full observations; expansion takes precedence over query and reports truncation. Use '*' only for deliberate cross-project reads. Search and expansion record retention access unless trackAccess=false. Use memory_recall when you need full, compact or narrative results in one call.
Inputs: project (required), limit, query, agentId, +2 more.
memory_snapshot_createA
Capture current exported memory state in the configured local snapshot directory, write state.json and commit it in that directory's Git repository. Requires Git and writable snapshot storage. Returns snapshot ID, commit hash, timestamp, message and counts, or a successful no-op message for an overlapping/no-change snapshot. This mutates local files and Git state; use memory_export when you only need returned JSON.
Inputs: message.
memory_team_feedA
Read the configured team's shared memory, pattern and observation feed, newest sharedAt first. Returns {items,total}; limit bounds returned items (default 20), while total counts all shared entries. Requires TEAM_ID and USER_ID; an unavailable team backend returns a setup message. Use memory_team_share to publish an item; this feed does not retrieve unshared personal memories.
Inputs: limit.
memory_timelineA
Retrieve a chronological observation window around an ISO timestamp or keyword to reconstruct nearby activity. before and after define the full window; follow nextOffset with offset until null. Returns observations and pagination metadata, bounded to 100 entries and 2 MiB per page. Omitted project searches all projects; specify an exact project to narrow it. Records retention access unless trackAccess=false. Use memory_smart_search for relevance-ranked discovery.
Inputs: anchor (required), after, before, offset, +3 more.
memory_verifyA
Read stored provenance for one memory or observation ID in an explicit project; use '*' only for deliberate cross-project verification. For a memory, returns {success:true,type:'memory',memory,citations,citationCount} with version/strength metadata and visible source observation/session metadata, including recorded confidence. For an observation, returns {success:true,type:'observation',observation,session,citations:[],citationCount:0}, with session:null if unavailable. Missing or out-of-scope IDs return {success:false,error:'not found'}; missing id/project returns an error. This read checks available citation records, not factual truth or completeness, and does not change confidence or access counts. Use memory_smart_search expandIds or memory_timeline to read source content.
Inputs: id (required), project (required).
memory_vision_searchA
Find stored image embeddings by text description or image similarity. Requires AGENTMEMORY_IMAGE_EMBEDDINGS=true and its image provider. Supply queryText, queryImageBase64 or queryImageRef; precedence is text, base64, then file reference. File references must be registered under the managed image store. Returns similarity-ranked image references with scores and session/observation IDs, plus total candidates; sessionId narrows scope. Use memory_smart_search for textual observations.
Inputs: topK, queryText, sessionId, queryImageRef, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 58 tools
The descriptions are unusually explicit about boundaries, repeatedly cross-referencing sibling tools (e.g. 'Use memory_recall for general topic searches', 'Use memory_graph_query for the separate entity/concept graph'). Still, with 58 tools there are several genuinely confusable clusters: memory_recall/memory_smart_search/memory_timeline/memory_file_history for retrieval, memory_patterns/memory_profile/memory_reflect/memory_insight_list for synthesis, and memory_export/memory_obsidian_export/memory_snapshot_create for output. The prose mitigates most of this, but an agent must read carefully to avoid misselection.
Every tool uses the memory_ prefix followed by a consistent snake_case verb_noun or resource_verb pattern (memory_save, memory_slot_create, memory_graph_upsert, memory_team_share). Sub-domains are grouped coherently (graph_*, slot_*, action_*, signal_*, sentinel_*, lesson_*), giving a predictable and highly legible naming scheme throughout.
58 tools is far beyond a practical single-server surface and effectively merges many subsystems (memory CRUD, entity graph, work items/actions, signals, team sharing, context slots, facets, diagnostics). While each tool is individually non-trivial, the sheer count creates cognitive overhead and makes the set feel like several servers bundled together. It is well past the 25+ threshold for 'too many'.
Coverage is remarkably thorough: full lifecycle for slots (list/get/create/append/replace/delete), actions, lessons, graph, facets, plus diagnostics, audit, archive, governance delete, export and sync. Minor gaps exist (lessons have no update, memories lack a direct edit/delete path beyond governance_delete), but core workflows have no dead ends.
Maintenance
Related MCP Connectors
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
Persistent memory for AI agents. Hosted cloud connector or local Windows install.
Shared memory for AI tools: save once, recall word for word from Claude, ChatGPT, Codex or Gemini.
Private memory for AI agents: save and recall facts across Claude Code, Codex, Cursor and ChatGPT.
Related MCP Servers
- AlicenseAqualityAmaintenanceLocal-first persistent memory for Claude Code and OpenAI Codex CLI. A single Rust binary captures, distills, searches, and injects project memory across sessions via hooks, MCP, CLI, and localhost REST.1533MIT
- AlicenseNot gradedqualityDmaintenanceProvides persistent, local-first memory for coding agents with Markdown as the source of truth, exposed via CLI, loopback API, MCP, and Codex hooks for context retrieval and durable writes.MIT
- AlicenseNot gradedqualityBmaintenanceEnables local-first personal knowledge management for Codex by turning conversations into a searchable archive, extracting durable facts, building a knowledge graph, and injecting relevant context into later sessions.9 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex to automatically recall and persist local project memory—such as decisions, constraints, goals, open loops, and milestones—across sessions via a secure, local MCP adapter.1Apache 2.0