A
licenseA
qualityC
maintenanceSelf-hosted MCP memory server that gives a multi-agent fleet one shared, git-backed memory for search, read, and write.
8
1
MIT
memory-mcp
by credp
The memory-mcp server provides a local MCP interface to a user-owned Git repository of Markdown memory files. By default, it runs in read-only mode, offering tools to browse, read, search, and inspect history/diffs. When configured with MEMORY_MCP_MODE=read-write, it can also capture new memories.
List memories: Enumerate files and directories at any path, optionally recursive, excluding
.gitcontents.Read memory: Retrieve the full UTF-8 text content of a file (up to 2 MiB) along with its relative path.
Search memories: Perform literal (non-regex) line-based search across UTF-8 memory files (files over 2 MiB are skipped). Supports case sensitivity, path scoping, and a configurable result limit (max 1,000 matches).
View history: Get bounded Git commit history (up to 100 commits) for the repository or a specific path, including commit hash, timestamp, author, and subject.
View diffs: Show tracked working-tree changes against
HEADand list untracked files. For an unborn repository, staged diff is reported.Capture new memories (only in read-write mode): Write new unstructured text content to a new, uniquely-named Markdown file. Files are not automatically committed.
Allows agents to manage durable memory stored in a local Git repository, including listing, reading, searching, viewing history and diffs, and capturing new Markdown files.
Click on "Install 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., "@memory-mcpsearch my memories for 'project roadmap'"
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.
memory-mcp
memory-mcp is a small, local Model Context Protocol server for a user-owned Git repository of durable memory. It gives agents reliable mechanisms to list, read, search, inspect history and diffs, capture unstructured text, or submit bounded changes for review.
The repository is the product's durable state.
memory-mcpis merely an interface to it.
It is deliberately not a database, ontology, knowledge graph, hosted service, agent, or automatic consolidation system. Markdown remains readable without this program. Git provides history, provenance, rollback, and the basis for future transactions. The agent—not the server—decides what a note means and how it should be organised: mechanism below, intelligence above.
┌──────────────┐
│ AI agent │
└──────┬───────┘
│ MCP
┌──────▼───────┐
│ memory-mcp │
│ │
│ mechanisms │
└──────┬───────┘
│ filesystem + Git
┌──────▼────────┐
│ memory repo │
│ │
│ Markdown │
│ Git history │
└───────────────┘Architecture
The Python core and each running server instance are bound to exactly one configured repository root. It validates repository-relative paths and provides dependency-light filesystem and Git operations. A thin adapter exposes those operations as MCP tools over stdio. Read-only and capture modes make no network requests and send no telemetry. Pull-request mode deliberately uses Git and a configured forge provider to refresh reviewed memory and publish proposals.
Installations that use more than one memory repository should configure a
separate MCP server instance for each repository. The MCP client gives each
instance a distinct name and starts it with that repository's own
MEMORY_MCP_REPOSITORY and, where appropriate, MEMORY_MCP_MODE. This keeps
repository selection and permissions at the MCP configuration boundary rather
than adding routing or cross-repository operations to memory-mcp.
The memory repository may use any layout. Names such as projects/, principles/, or inbox/ carry no protocol meaning. V1 understands only a repository, relative paths, text files, and Git changes.
Python 3.11+ was chosen for its mature standard-library filesystem, subprocess, atomic-file, and testing support. The official MCP SDK is the sole runtime dependency. Text search is implemented locally in Python, so ripgrep is not required. Git must be installed.
Related MCP server: Engram
Install and configure
Using uv:
git clone https://github.com/credp/memory-mcp.git
cd memory-mcp
uv syncCreate or choose a separate Git repository for memory:
mkdir -p "$HOME/Projects/memory"
git -C "$HOME/Projects/memory" initSet MEMORY_MCP_REPOSITORY in the process environment to that repository's root. Do not put a private absolute path in a committed configuration file.
The server defaults to read-only mode. In this mode it does not register or
advertise any tool capable of changing the memory repository. To deliberately
enable new-file capture, set MEMORY_MCP_MODE=read-write. To use reviewed
contributions instead, set MEMORY_MCP_MODE=pull-request. Any other value is
rejected, so a typo cannot accidentally enable writes.
An MCP client configuration commonly looks like:
{
"mcpServers": {
"memory": {
"command": "uv",
"args": ["--directory", "/path/to/memory-mcp", "run", "memory-mcp"],
"env": {
"MEMORY_MCP_REPOSITORY": "/path/to/private/memory"
}
}
}
}The exact outer configuration format varies by client. For a global install, uv tool install . provides the memory-mcp command.
Updating the memory repository
General memory updates may happen through ordinary filesystem and Git tools, or through the optional pull-request workflow. In either case, the Git repository remains the source of truth.
The only current MCP write mechanism is the optional capture tool, which is
available when a server instance is explicitly configured with
MEMORY_MCP_MODE=read-write. Capture only creates a new untracked Markdown file
and is not a general editing or repository-maintenance interface. In the default
read-only mode, all updates must happen outside the MCP server.
In pull-request mode, refresh fetches and fast-forwards a clean checkout of
the configured reviewed branch. propose_memory creates one new Markdown file
from that remote base in a disposable worktree, commits only that file, pushes
a new branch, and asks the configured provider to open a review. It never
approves or merges reviews, never rewrites history, and refuses a dirty primary
checkout or an existing destination path.
GitHub is the first provider. It uses the gh CLI and its existing
authentication, so install gh and authenticate the service identity before
starting the server. For unattended deployment, give that identity only the
repository permissions needed to read contents, push proposal branches, and
open pull requests. Supplying and rotating a GitHub App installation token is
an operator concern; do not put it in the memory repository or MCP arguments.
GitLab can be added as a separate provider without changing the proposal
service or MCP contract.
{
"MEMORY_MCP_MODE": "pull-request",
"MEMORY_MCP_REPOSITORY": "/path/to/private/memory",
"MEMORY_MCP_PROPOSAL_PROVIDER": "github",
"MEMORY_MCP_PROPOSAL_REMOTE": "origin",
"MEMORY_MCP_PROPOSAL_BASE_BRANCH": "main",
"MEMORY_MCP_PROPOSAL_BRANCH_PREFIX": "memory-proposal"
}Protected local service
When Codex must not inherit the GitHub credential, install pull-request mode as
a persistent loopback service under a separate Unix identity. This installer is
Linux/systemd-specific. It requires an existing clean checkout on main, a
credential-free https://github.com/... origin, the gh CLI, and root access.
Create a fine-grained PAT restricted to the memory repository with repository
permissions Contents: read and write and Pull requests: write. Then run:
sudo "$(command -v memory-mcp-service)" install home-operations \
--repository /srv/memory/home-operations \
--port 8771 \
--take-ownershipThe ownership flag is deliberately mandatory because the installer recursively
transfers the checkout to the dedicated memory-mcp-home-operations service
account. The installer prompts for the PAT without echo; it never accepts the
token in command-line arguments. It stores the source credential at
/etc/memory-mcp/home-operations/github_pat with root-only permissions and
passes it to the service through systemd's credential mechanism.
It also installs a root-owned pre-push hook and forces the service to use it;
the hook rejects deletions, tags, main, and every branch outside
memory-proposal/*. This is a local mistake-prevention control, not a substitute
for server-side branch protection against a stolen PAT.
The command prints the corresponding Codex registration command:
codex mcp add home-operations --url http://127.0.0.1:8771/mcpCodex knows only the loopback MCP address. The PAT, writable checkout, GitHub CLI and outbound provider access remain in the separate service process. Any local process able to reach that loopback port can invoke the bounded MCP tools, so use host firewall rules when local users require different tool access.
Review the generated unit without installing anything:
memory-mcp-service print-unit home-operations \
--repository /srv/memory/home-operations \
--port 8771Rotate the PAT without putting it in shell history:
sudo "$(command -v memory-mcp-service)" rotate-token home-operationsRemove the service and credential while deliberately preserving the repository:
sudo "$(command -v memory-mcp-service)" uninstall home-operationsUninstall leaves the dedicated service account and repository ownership intact so it cannot orphan repository files under a deleted numeric UID. Reassign or remove those explicitly after preserving any required Git work.
Codex
Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration on the same host. With this repository checked out locally, add the server from a shell as follows, replacing the memory path if necessary:
cd /path/to/memory-mcp
uv sync
codex mcp add memory \
--env MEMORY_MCP_REPOSITORY="$HOME/Projects/memory" \
-- uv --directory "$PWD" run memory-mcpUse an absolute path for the memory repository. The shell expands $HOME and
$PWD before Codex stores the configuration. Confirm the result with:
codex mcp listRestart Codex after adding or changing the server. In the Codex terminal UI,
/mcp shows the active MCP servers and their tools.
Tell Codex about persistent memory
The server advertises its purpose through the MCP instructions field, but a
small global Codex instruction makes the intended relationship explicit: this
repository is the user's persistent context across agents, chats, and projects,
not merely a tool to use when working on memory-mcp itself.
Add the following boilerplate to $CODEX_HOME/AGENTS.md. CODEX_HOME defaults
to ~/.codex, so the usual location is ~/.codex/AGENTS.md:
## Persistent memory
A user-owned persistent memory is available through the `memory` MCP.
Use it as the primary place to read or store durable context relevant to the
user's request, including prior decisions, preferences, constraints, projects,
and historical reasoning.
Search memory when existing context could materially improve the task. Do not
assume every request requires memory.
Treat retrieved memories as supporting context, not unquestionable truth.
Prefer reviewed/current material over inbox, candidate, or historical material.
Store information only when it is likely to remain useful across future agents
or conversations. Do not store credentials, secrets, or sensitive information
unless the user explicitly requests it.Codex reads this global file before project-level AGENTS.md files. If
$CODEX_HOME/AGENTS.override.md exists and is non-empty, Codex uses it instead
of the global AGENTS.md; put the boilerplate there as well, or remove the
override, if the memory guidance is not being loaded. Start a new Codex session
after changing the file because the instruction chain is assembled once per
run.
This is intentionally a relevance rule, not a requirement to load memory at the start of every session. Codex should consult memory when it can improve the user's task and leave it alone for self-contained requests.
To update a source-checkout installation when this upstream repository gains new commits:
cd /path/to/memory-mcp
git pull --ff-only
uv sync
uv run pytestThen restart Codex so it launches the updated server. The MCP configuration
does not need to be added again because it continues to point at the checkout.
git pull --ff-only deliberately stops instead of creating an implicit merge
if the local branch and upstream have diverged; review or preserve local work
before resolving that situation.
Tools
list_memories(path="", recursive=false)lists directory entries..gitinternals are excluded.read_memory(path)reads a bounded, valid UTF-8 text file and returns relative-path metadata.search_memories(query, path="", case_sensitive=false, limit=100)performs deterministic literal line search. Oversized and malformed files are skipped.history(path="", limit=20)returns bounded Git history with commit, timestamp, author, and subject.diff(path="")returns tracked working-tree changes againstHEADand separately lists untracked files. In an unborn repository it reports the staged diff.capture(content, destination="")is available only in explicitread-writemode. It writes the content unchanged (apart from ensuring a final newline) to a new Markdown file.destinationis a configurable, existing relative directory; the neutral default is the repository root. Creation uses an exclusive filename and does not stage or commit anything.refresh()is available only inpull-requestmode. It requires a clean checkout on the configured base branch, fetches that branch, and applies only a fast-forward update.propose_memory(path, content, title, rationale, source_run_id="")is available only inpull-requestmode. It accepts a new repository-relative Markdown path, scans all outbound text for common credential shapes, creates an isolated contribution, and returns the review URL and Git provenance.
File reads are limited to 2 MiB, search skips files over 2 MiB, history is limited to 100 commits, and search is limited to 1,000 matches. These conservative v1 bounds keep MCP responses manageable.
Security and privacy
Each MemoryRepository instance is a security boundary. All external paths are relative to its exact Git root. Absolute paths, traversal with .., and symlinks resolving outside the root are rejected. Recursive operations do not follow symlinks, and returned data does not reveal the configured absolute path.
Each server instance exposes one repository and defaults to read-only access.
Operators can explicitly opt into read-write capture with
MEMORY_MCP_MODE=read-write. Multiple repositories are exposed through
separately named MCP server instances, so each repository retains an independent
security and permission boundary. A server instance never routes to another
repository or performs cross-repository operations.
Repository content stays local in read-only and capture modes. Pull-request mode sends the proposed content, title, rationale, branch, and commit to the Git remote and review provider. There is no external indexing, analytics, or telemetry. MCP clients, agents, Git hosting, and the narrowly scoped service identity are therefore part of that mode's trust boundary.
Capture creates an obvious untracked file with mode 0600. Pull-request mode
never resets or discards local work, rewrites history, approves reviews, or
merges them. Its contribution branches are intentionally visible on the remote;
if review creation fails after a successful push, the branch remains available
for diagnosis or manual review rather than being deleted implicitly.
Development
uv sync --extra dev
uv run pytestTests create isolated temporary Git repositories and cover listing, reading, literal search, history, diff, capture, dirty trees, spaces, Unicode, traversal, escaping symlinks, missing/non-Git/empty repositories, malformed and oversized files, capture filename collisions, and Git failures.
To prepare a patch release from a clean working tree:
make releasemake release defaults to a patch increment (for example, 0.0.2 to 0.0.3);
make release BUMP=patch is the explicit equivalent. Use
make release BUMP=minor or make release BUMP=major when those larger version
increments are intended. The command runs the tests, updates pyproject.toml
and uv.lock, creates a release commit, and adds the matching annotated Git
tag locally. It prints the separate git push command needed to publish the
release.
Roadmap
Phase 1 (implemented): read-only-by-default list, read, textual search, history, and diff; optional explicit read-write capture.
Phase 2 (implemented for new memories): optional GitHub pull-request contributions created in isolated worktrees, with a provider boundary for other forges. Broader edit, rename, and deletion proposals remain future work.
Phase 3: improve support and documentation for multi-memory installations by running one separately named MCP server instance per repository. Each instance remains bound to one repository and has its own access mode; repository routing, discovery, and cross-repository operations remain outside the server.
Possible later experiments include semantic search, local embeddings, related-memory discovery, structured frontmatter, and agent-assisted consolidation. They must remain optional layers; the core will never require them.
The governing design test is simple: if memory-mcp disappeared tomorrow, the user would still own a clean, understandable, useful Git repository containing all memories and history.
Available Tools
5 toolsdiffA
Return tracked working-tree changes against HEAD and list untracked files.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden. It states what is returned ('tracked working-tree changes' and 'untracked files') but does not disclose output format, side effects, prerequisites (e.g., being a git repo), or whether the operation is read-only, though 'Return' implies read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action. It contains no fluff and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool, the description covers the main function, but it omits the path parameter semantics and return format details. Given the tool's simplicity and lack of annotations, this is adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions no parameters. The schema defines an optional 'path' parameter, but the description provides no explanation of its meaning or effect, and schema description coverage is 0%. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with specific verb 'Return' and identifies the resource: 'tracked working-tree changes against HEAD and list untracked files.' It distinguishes the tool from sibling memory-related tools, which are unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
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 the tool (to inspect working-tree changes and untracked files) without explicit alternatives. No exclusions are needed since siblings are unrelated, but the description could explicitly say 'use this for git diff'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
historyB
Return bounded Git commit history for the repository or a relative path.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the history is 'bounded' and scoped to a repository or path, but omits whether the operation is read-only (implied by 'Return'), commit ordering, branch scope, and error behavior. This is moderate disclosure with meaningful gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no filler. The main action and object are front-loaded, and every word adds value. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and lack of annotations, the description leaves questions unanswered: whether it requires being inside a Git repo, whether it shows only the current branch, and the exact behavior of the limit parameter. The output schema likely covers return format, but the description could more fully contextualize the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds partial meaning by referencing 'repository or relative path' for the path parameter and 'bounded' for the limit, but it does not explicitly define the limit as a maximum count or explain defaults, making it insufficient for full understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns Git commit history, scoped to the repository or a relative path. This specific verb-resource pairing distinguishes it from sibling tools like diff (which shows changes) and memory tools, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Usage must be inferred from the name and purpose; there is no guidance on choosing it over diff or capture.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_memoriesB
List files and directories below a repository-relative path.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| recursive | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations absent, the description carries the full burden of behavioral disclosure. It states that the tool lists files and directories, but omits key behaviors such as whether recursion is supported (despite the 'recursive' parameter), what happens when the path is invalid, or whether hidden files are included. No side effects are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded. It avoids unnecessary words and communicates the core function efficiently. There is no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and has an output schema, but the description is still under-specified. It does not mention the recursive parameter, which significantly affects behavior, nor does it provide any context about typical usage. No annotations exist to fill the gaps, leaving the description incomplete for a reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate adequately. The phrase 'repository-relative path' adds meaning to the 'path' parameter, but the 'recursive' parameter is completely unaddressed. The description adds minimal value over the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource as 'files and directories below a repository-relative path'. This clearly distinguishes it from sibling tools like read_memory (which presumably reads content) and search_memories (which searches).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention any exclusions, prerequisites, or scenarios where another tool would be more appropriate. The use case is implied by the name and description but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_memoryA
Read a UTF-8 text memory at a repository-relative path.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It notes the operation is a 'read' (implying non-destructive) and specifies UTF-8 encoding, but does not disclose error conditions, permissions, or side effects (or lack thereof). It provides basic transparency but leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence. Every word contributes to the meaning, making it highly concise and well-structured for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, output schema present, no nested objects), the description provides sufficient context for basic use. It covers the core operation and path semantics. However, it lacks explicit guidance on error scenarios or when to prefer this over siblings, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'path' with no description, and the schema description coverage is 0%. The description compensates by adding the 'repository-relative' qualifier, which clarifies that the path is relative to the repository root. This adds meaning beyond the raw schema, though it does not elaborate on path format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Read a UTF-8 text memory at a repository-relative path.' It specifies a specific verb ('read') and resource ('memory'), and the scope is distinct from siblings like list_memories or search_memories by focusing on reading a single memory at a given path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific repository-relative path is known, but it does not explicitly contrast with sibling tools or provide exclusions. For example, it doesn't say 'use this instead of list_memories when you know the exact path.' Usage is implied but not explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_memoriesB
Search UTF-8 memory files for literal text, returning matching lines.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No | ||
| query | Yes | ||
| case_sensitive | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
B3.4/5.0
Behavior3/5
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 adds some useful context by specifying 'UTF-8' encoding, 'literal text' (implying exact matching, not regex), and 'returning matching lines' (indicating output format). However, it omits other behavioral aspects such as what happens with no matches, whether the search covers entire directories or specific files via the 'path' parameter, and how limit and case_sensitive affect behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main action and resource. Every word contributes value; there is no filler, redundancy, or unnecessary detail. It is an excellent example of efficient, focused description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which covers return values), the description is incomplete for a tool with 4 parameters and no annotations. It does not explain the role of the optional 'path' parameter (e.g., searching a specific file vs all memory files), the default behavior for case_sensitive or limit, or any edge cases. This leaves the agent without enough context to use the tool reliably in varied scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 0% of parameter descriptions, so the description must compensate. It adds meaning to the 'query' parameter by clarifying that it searches for literal text in memory files and returns matching lines. However, it does not explain the 'path', 'limit', or 'case_sensitive' parameters, their defaults, or how they affect the search, leaving significant gaps in understanding the tool's full behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search'), a clear resource ('UTF-8 memory files'), and a distinct scope ('literal text, returning matching lines'). This clearly differentiates it from siblings like list_memories, read_memory, history, diff, and capture, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention situations where search_memories is preferred or where tools like read_memory or history might be more appropriate. The usage context is only implied by the tool name and basic description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
B3.4/5.0
Disambiguation5/5
Each tool targets a distinct operation: listing, searching, reading, viewing history, and viewing diffs. No two tools overlap in purpose.
Naming Consistency3/5
Three tools follow a verb_noun pattern (list_memories, search_memories, read_memory), but history and diff are bare nouns, creating a mixed convention. Still readable but not fully consistent.
Tool Count5/5
Five tools is a well-scoped size for a memory management server, providing essential read and inspection capabilities without unnecessary bloat.
Completeness2/5
The toolset is read-only, missing create, update, and delete operations for memories. Agents cannot modify the memory store, which is a significant gap for a management server.
Maintenance
ActivityMaintained
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
Persistent, inspectable memory for AI agents with lineage, correction, and a hosted MCP endpoint.
A MCP server built for developers enabling Git based project management with project and personal…
Related MCP Servers
- AlicenseAqualityAmaintenanceA self-hosted MCP server that gives AI agents shared, long-term memory over a git-backed folder of markdown, enabling persistent knowledge search, read, and write without a database.162110MIT
- AlicenseAqualityCmaintenanceA local-first MCP server that provides a shared Markdown-based memory for AI coding agents, enabling cross-agent context persistence via tools like memory_search and memory_capture.101MIT
- AlicenseNot gradedqualityBmaintenanceMCP server providing persistent, local-first memory for AI agents via Markdown files in a git repo, with search, branching, and auditability.172MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/credp/memory-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server