python-memory

This Memory MCP Server runs entirely in-memory with strict validation rules for entities, observations, and relations. It exposes a set of tools to manage a knowledge graph: create and validate entities, add observations, create and delete relations, query the graph, search memory with natural language terms, and flush the in-memory store. The server enforces naming conventions, supported entity types, non-empty observations, and a restricted set of relation types to maintain data consistency. Use the provided tools to build and interrogate your graph, then persist results by writing observations or exporting the memory as needed.

You can create entities with create_entities, add observations with add_observation, and establish relationships with create_relation. Get a snapshot of the graph using get_graph or fetch a specific entity with get_entity. The search_memory tool supports natural language queries with temporal and activity-focused terms, offering fuzzy matching and weighted scoring across names, types, and observations to surface relevant entities and relations. Errors are categorized (NOT_FOUND, VALIDATION_ERROR, etc.) to help you diagnose issues quickly.

To explore the graph, start by creating a small set of entities (e.g., a person and a project), attach observations, and then connect them with a relation like created or belongs-to. As you expand the graph, rely on search_memory to locate related entities and validate that all relations reference existing entities, preserving the integrity of your knowledge graph.

Prerequisites:

• Python (3.8+) installed on your system
• Access to run the mcp CLI (Claude Desktop or compatible environment)
• A writable path for MEMORY_FILE_PATH to persist memory across sessions

Install steps:

1. Ensure you have the MCP CLI available in your environment. If not, install it per your environment's guidance (e.g., via pipx or npm/yarn if applicable).
2. Create or prepare your memory file path, for example: /path/to/memory.jsonl
3. Start the server using the MCP CLI with the required environment variable:

mcp install main.py -v MEMORY_FILE_PATH=/path/to/memory.jsonl

4. Verify the server is running and accessible via your MCP tooling by attempting a simple get_graph call or listing entities using the provided tools.

Notes:

• The MEMORY_FILE_PATH is required to initialize the in-memory knowledge graph store.
• If MEMORY_FILE_PATH is missing or unwritable, the server will fail to start or will not persist data between runs.

Tips and considerations:

• Supported entity types: person, concept, project, document, tool, organization, location, event.
• Entity names must start with a lowercase letter, use lowercase letters/numbers/hyphens, and be unique within the graph (max 100 chars).
• Observations must be non-empty, up to 500 characters, and unique per entity; include a timestamp when relevant.
• Allowed relation types: knows, contains, uses, created, belongs-to, depends-on, related-to. Ensure both source and target entities exist before creating a relation.
• When using search_memory, you can leverage temporal terms (most recent, last, latest) and general queries (workout, exercise). The system uses an 80% similarity threshold for fuzzy matching and weighs names, types, and observations to rank results.
• If you encounter NOT_FOUND or VALIDATION_ERROR, verify entity names, relation endpoints, and that you’re referencing existing entities before retrying.
• Flush memory via flush_memory to clear in-memory state (note: this may be irreversible for the current session if not persisted to your memory file).
• Export or back up memory periodically if you require long-term preservation beyond in-memory state.