memento-context

Memento Context is a Model Context Protocol (MCP) server that provides persistent memory capabilities for AI assistants. It allows AI models to save, retrieve, and manage scoped context across different sessions and projects safely on your local machine.

What is Memento Context?

Memento Context is not a traditional knowledge base or a long-term file storage system. Instead, it is designed as a "living context" layer for AI assistants.

The Concept

A "memento" is a short, high-impact note—usually no more than a few lines—that captures preferences, rules, or specific project context. These notes are automatically injected into the AI's instructions at the start of every session.

• It IS: A place for "Wait for the DB connection before calling the auth helper", "I prefer concise Spanish responses", or "Ignore the legacy/ folder during this migration".
• It IS NOT: A heavy knowledge base designed for complex semantic search or RAG. Conversations can be saved as explicit attachments to a memento, but the core model remains direct, deterministic context injection rather than large-scale document retrieval.

By keeping memories small and scoped, they remain relevant and don't overwhelm the AI's reasoning capacity.

The Ecosystem of Memory: Where does Memento fit?

To work effectively, Memento should coexist with other forms of documentation without overlapping. Think of it as the "Scar Tissue" of your project—the memory of past experiences that shapes future behavior.

Memory Type	Role	Content	Audience
README.md	The Handbook	Public overview, installation, and usage.	Humans & AI
AGENTS.md	The Constitution	Permanent laws: coding standards, architecture, and persona.	AI Assistants
Memento	The Scar Tissue	Dynamic lessons, ephemeral decisions, and personal preferences.	AI (Specific to You)

When to Memento?

• Dynamic Learning: "Yesterday we decided to pivot to Vitest because Jest was giving us timeout issues."
• Contextual Scars: "You've failed to handle the edge case in the parser 3 times; from now on, always check for null bytes first."
• Ephemeral Focus: "For this session, prioritize refactoring the auth/ module over adding new features."

When NOT to Memento?

• Official Standards: If it's a rule that everyone in the team should follow forever, it belongs in AGENTS.md.
• Public Knowledge: If a human needs to know how to install the project, it belongs in README.md.

The Zero-Dependency Advantage

Unlike most MCP servers, memento-context is built using Zero External Dependencies. It uses only the Python standard library to implement the JSON-RPC protocol. This ensures:

• Instant Load Times: No heavy package analysis at startup.
• Maximum Portability: Runs anywhere Python is available without pip install headaches.
• High Security: Zero risk of supply chain attacks from third-party libraries.

How it Works

The interaction with Memento Context follows a simple, automated lifecycle:

1. Session Bootstrap: At the start of every chat, the assistant calls init_memento. This automatically loads all relevant global and repository-scoped notes into its active context, so it "remembers" you and your project immediately.
2. Natural Learning: As you talk, the assistant is trained to recognize important information—like a new coding preference or a project-specific rule—and will offer to save it using save_memento.
3. Explicit Instructions: You have full control. You can explicitly say "Remember that this specific module has a memory leak if we use the default constructor" or "Save a note about the workaround we found for the build issue", and the assistant will persist that information for all future sessions.
4. Conversation Attachments: On explicit request only, the assistant can save a full conversation or summary with save_conversation, and later attach related files with save_memento_attachments. These attachments are stored alongside the memento and can be retrieved with get_memento_attachments when the extra detail is needed.

Features

• Global Memory: Store preferences, rules, and facts about the user that persist across all interactions.
• Repository Memory: Store project-specific context, conventions, and architectural decisions automatically scoped to the current working directory.
• Conversation Attachments: Save full conversations, summaries, and related files as attachments linked to a memento, only when explicitly requested by the user.
• Intelligent Hashing: Avoids path collisions natively by generating safe repository folder IDs.
• Deterministic Storage: Saves everything locally using a scalable JSON Envelope format.

Installation

Note

memento-context is currently in early development. Standard installation via PyPI (pip install memento-context) will be available starting with the first stable release.

Quick Install (Recommended)

You can install the server in a single command using our setup scripts. This clones the repository into a local hidden folder and installs the executable globally.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/FranBarInstance/memento-context/main/scripts/install.sh | bash

Windows (PowerShell):

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/FranBarInstance/memento-context/main/scripts/install.ps1" -OutFile install.ps1; .\install.ps1

Manual Install from Source

If you prefer to install manually from the source code:

git clone https://github.com/FranBarInstance/memento-context.git
cd memento-context
pipx install .  # Recommended approach
# or: pip install .

For developmental purposes, use the editable mode:

pipx install -e .

Running the Server

Because it is defined in the pyproject.toml scripts, the installation automatically creates a globally available executable. You can start the MCP stdio standard process anywhere by simply calling:

memento-context

IDE / MCP Client Configuration

To use memento-context with an MCP-compatible client (like Claude Desktop or MCP VSCode plugins), configure the client's mcp.json settings file to connect to the executable:

{
  "mcpServers": {
    "memento-context": {
      "command": "memento-context",
      "args": []
    }
  }
}

Available MCP Tools

The server exposes the following tools to the AI capabilities out of the box:

• init_memento: Loads behavior instructions and bootstraps the context state.
• get_mementos: Fetches specific memory environments (global or repo).
• save_memento: Saves a new memory string into a target scope.
• save_conversation: Saves a conversation or summary as a memento with attachment files. Intended only for explicit user requests.
• save_memento_attachments: Copies one or more local files into the attachment directory of an existing memento.
• get_memento_attachments: Reads the attachment files associated with a specific memento.
• delete_memento: Completely removes a recognized memory.
• move_memento: Recategorizes a memory, transferring it seamlessly between repository scope and global scope.

Storage Architecture

All AI memories are saved inside the user home directory (~/.memento-context/).

• Global records: ~/.memento-context/global/mementos.json
• Repository records: ~/.memento-context/repos/<slug>__<hash>/mementos.json

When a memento includes attachments, the server creates a sibling directory named <memento_id>_attachments/ next to the corresponding mementos.json file. That directory may contain:

• conversation.md for a full saved conversation
• summary.md for a shorter narrative summary
• Any additional files copied with save_memento_attachments

Example layout:

~/.memento-context/
├── global/
│   ├── mementos.json
│   └── memento_2026-04-10_abc12345_attachments/
│       ├── conversation.md
│       └── summary.md
└── repos/
    └── my-project__a1b2c3d4e5/
        ├── mementos.json
        └── memento_2026-04-10_def67890_attachments/
            ├── conversation.md
            └── architecture-notes.md

License

This project is licensed under the MIT License.

See: https://github.com/FranBarInstance/memento-context