Skip to main content
Glama
fariborzvrm

Memento

by fariborzvrm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Memento

Give your coding agent persistent memory.

Memento is a tiny MCP server that turns a plain folder of markdown files into typed memory for AI coding agents: decisions, contracts (invariants), tasks, evaluations and session logs. Your agent can search it, extend it, and update entries by id — while the memory stays as plain, greppable, committable markdown in your repo. Works with OpenCode, Claude Code and Codex CLI — all three speak MCP over stdio, so one server covers all of them.

What it does

  • On session start the agent loads memory with read_all.

  • During work it records choices (write), checks what's known (search), and updates entries (update).

  • At session end it leaves a summary (log).

No daemon, no database, no web UI. One self-contained script — no install step.

Related MCP server: context-vault

Install

1. Install uv (once per machine)

uv downloads and runs the server with its one dependency (mcp) in an isolated, cached environment — no pip, no venv, no clone. Windows:

winget install --id=astral-sh.uv -e

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Register the server in your CLI (no download needed)

Point your CLI at the script URL, pinned to the v1.0.0 tag so it never changes under you. (Use main instead of v1.0.0 if you want to track the latest.)

OpenCode

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "memento": {
      "type": "local",
      "command": [
        "uv", "run",
        "https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py"
      ],
      "enabled": true
    }
  }
}

Claude Code

claude mcp add memento -- uv run https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py

Or manually in ~/.claude.json:

{
  "mcpServers": {
    "memento": {
      "command": "uv",
      "args": ["run", "https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml (or per-project .codex/config.toml):

[mcp_servers.memento]
command = "uv"
args = ["run", "https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py"]

Verify

Ask the agent: "List your available MCP tools." — you should see 5 memento tools.

3. Add to a project

Run in the project root:

uv run https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py init

This creates .memento.toml (memory_dir = "docs/memory") and writes the memory protocol into AGENTS.md (both skipped if already present).

Claude Code only — add one pointer line to CLAUDE.md:

See AGENTS.md for the memory protocol.

(A symlink also works but needs Developer Mode on Windows; duplicating the snippet works but can drift.)

How the memory folder is found

Resolved per tool call: the MEMENTO_ROOT env var if set → the nearest .memento.toml walking up from the working directory → docs/memory under the working directory. The folder and its five seed files are created on first write.

Offline / pip fallback

Prefer a local copy, or can't use uv?

# local copy, still no venv juggling
curl -o memento_server.py https://raw.githubusercontent.com/fariborzvrm/memento-mcp/v1.0.0/memento_server.py
# point your CLI at: ["uv", "run", "/path/to/memento_server.py"]

# or plain Python (3.11+)
pip install mcp
python memento_server.py

Tools

  • read_all() — every markdown file in the memory folder, concatenated, each prefixed with a <!-- file: NAME --> marker.

  • search(query, file=None) — case-insensitive substring match over entry titles, bodies, tags and status. Returns full entry blocks with id + file.

  • write(type, title, body, tags=None) — append a new entry with a fresh sequential id. type: decision, contract, task, log, evaluation (unknown types get their own {TYPE}S.md).

  • update(entry_id, status=None, title=None, body=None, tags=None) — patch an entry in place; only the fields you pass change.

  • log(body, tags=None) — append a session log entry; the first line of body becomes the title.

Entry format

Entries are markdown sections with an id comment; anything before the first marker (frontmatter, intros) is preserved:

<!-- id: dec-001 -->
## Use Postgres for persistence

**Status:** active
**Tags:** db, arch

We chose Postgres over SQLite because the eval workload needs
concurrent writers and JSONB for schema hints.

Limitations

  • No locking — assume one agent per project.

  • Linear search — fine under ~2000 entries.

  • Whole-file rewrite on write.

  • A broken .memento.toml is reported as an error, not silently ignored.

License

MIT — see LICENSE.

Available Tools

5 tools
logA

Append a session log entry. The first line of body becomes the title.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
tagsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/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 the non-obvious behavior that the first line of body becomes the title, which is valuable. However, it does not explain side effects, permissions, or how the session log is affected beyond appending, so transparency is partial.

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?

Two short sentences with no filler. The main action is front-loaded, and the key title-extraction behavior is stated in the second sentence, which earns its place.

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?

For a simple two-parameter logging tool with an output schema, the description covers the required body behavior and leaves tags inferable. It is nearly complete, though a note on when to use logging vs. other tools would make it fully self-contained.

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?

Schema description coverage is 0%, so the description must add meaning. It explains the semantics of the required body parameter (first line serves as title), but says nothing about the optional tags parameter. The name 'tags' is self-explanatory, so this is acceptable but not complete.

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 action (append) and resource (session log entry), making the tool's purpose immediately clear. It is distinct from sibling tools like write/update which imply modifying data, whereas this tool logs entries.

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?

No guidance is given about when to use this tool instead of write/update/read_all/search. There are no conditions, exclusions, or alternative suggestions, leaving the agent to infer use from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_allA

Load the whole project memory: every markdown file in the memory folder, concatenated, each prefixed with a marker.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/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 disclosing behavior. It specifies that this is a read-only operation that loads all markdown files, concatenates them, and prefixes each with a marker. This is transparent about the main behavioral details, though it does not discuss ordering, size limits, or folder location specifics.

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 sentence that is dense with useful information: the action, the resource, the scope, the concatenation behavior, and the marker format. No filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only tool with an output schema available, the description is complete. It tells the agent exactly what will be loaded and how the output is structured, leaving no operational ambiguity.

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 tool has zero parameters, so the baseline is 4. There is nothing for the description to add about parameter semantics, and the schema already trivially covers the empty parameter set.

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 ('Load'), a clear resource ('the whole project memory'), and the exact scope ('every markdown file in the memory folder'). It also explains the output format (concatenated with file markers), which distinguishes it from sibling tools like search or log.

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 clearly implies when to use this tool: when the agent needs the entire project memory context. It does not explicitly name alternatives or exclusion conditions, such as 'use search for targeted queries,' but the context is clear enough for an agent to select it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

updateA

Update an existing entry by id (e.g. "dec-001"). Only the fields you pass are changed; the rest of the file is preserved byte-for-byte.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNo
tagsNo
titleNo
statusNo
entry_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/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 disclosure. It usefully reveals the key behavioral trait: partial updates that preserve the rest of the file byte-for-byte. This goes beyond the schema and reduces ambiguity about destructive overwriting, though it does not discuss failure cases or permissions.

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?

Two short sentences, no filler, and the core purpose is front-loaded. Every phrase adds value, especially the 'byte-for-byte' preservation detail.

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?

The description covers the fundamental update behavior and benefits from an output schema, so return values are likely handled. However, with zero parameter documentation and no explicit guidance on when to use update versus write, the tool definition is only minimally sufficient for an agent to select and invoke it correctly in all cases.

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 needed to compensate by explaining the parameters. It only gives an id example ('dec-001') and speaks generally about 'fields you pass', but does not clarify body, tags, title, or status beyond their names. The schema itself provides no descriptions, leaving the agent with limited semantic grounding.

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 and resource: 'Update an existing entry by id'. It also clarifies that this is a partial update ('Only the fields you pass are changed'), which differentiates it from sibling tools like write by establishing an update-in-place semantic.

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 gives clear context for when to use it: updating an existing entry by id, with only the provided fields changed. It does not explicitly name alternatives or exclusion conditions, but the 'existing entry' and 'preserved byte-for-byte' language makes the intended use case reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

writeA

Write a new memory entry. type: decision | contract | task | log | evaluation (unknown types get their own {TYPE}S.md file). Appends to the matching file with a fresh sequential id and Status: active.

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyYes
tagsNo
typeYes
titleYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full transparency burden. It discloses key behaviors: appends to the matching file, assigns a fresh sequential id, sets 'Status: active', and creates a new {TYPE}S.md file for unknown types. It does not cover permissions or error behavior, but the core side effects are clearly communicated.

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 two sentences with no filler. The primary action is front-loaded, and the type semantics and append behavior are packed into the remaining sentence. Every clause adds useful information.

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?

The description plus input schema covers the required fields, the valid type values, the file-based append behavior, and the handling of unknown types. Since an output schema exists, explaining the return value is unnecessary. The main gap is the lack of guidance for choosing between write and its sibling tools.

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?

Schema description coverage is 0%, so the description must compensate. It meaningfully enriches the 'type' parameter by enumerating valid values and explaining the file-naming behavior for unknown types. However, 'title', 'body', and 'tags' receive no semantic explanation beyond their property names and schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb and resource: 'Write a new memory entry.' It also clarifies that this is an append operation with a fresh sequential id, which distinguishes it from an update or overwrite. However, it does not explicitly name or differentiate the sibling tools like update or log.

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?

No guidance is given about when to use write versus the sibling tools update, log, search, or read_all. The description implies this is for creating new entries, but it never states that update should be used for existing entries or what log is for.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv1.0.0
    • First observedlog
    • First observedread_all
    • First observedsearch
    • First observedupdate
    • First observedwrite
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 5 tools

Disambiguation4/5

The tools are mostly distinct: read_all and search differ in scope (full dump vs targeted lookup), and write/update/log each have clear intents. The only minor ambiguity is write with type 'log' overlapping the dedicated log tool, but descriptions sufficiently clarify the difference.

Naming Consistency4/5

All tool names are imperative verbs (search, write, update, log, read_all), which makes them predictable. The slight deviation is 'read_all' with an underscore suffix versus the single-word names of the other tools, but the pattern is still coherent.

Tool Count5/5

Five tools is well-scoped for a memory-management server. Each tool covers a distinct core operation—full read, search, create, update, and session logging—without bloat or trivial fragmentation.

Completeness4/5

The toolset covers reading, searching, writing, updating, and logging, which handles the main memory lifecycle. There is no explicit delete, but update can set status to inactive, so the gap is minor and workaroundable.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Stoa

    BrettNye
    A
    license
    Not graded
    quality
    B
    maintenance
    Persistent shared memory for AI coding agents that turns a folder of markdown files into searchable memory across sessions, repos, and machines.
    11 npm
    Functional Source , Version 1.1, MIT Future

  • context-vault

    fellanH
    F
    license
    Not graded
    quality
    B
    maintenance
    Persistent memory for AI agents enabling saving, searching, and managing knowledge across sessions with local markdown files.
    2
    -

  • agent-memory

    jcyamacho
    F
    license
    Not graded
    quality
    F
    maintenance
    Persistent memory for MCP-powered coding agents, allowing LLMs to remember preferences, project context, and decisions across sessions via Markdown files.
    16 npm
    -

  • RepoRecall

    esannkv
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides 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