memex-mcp
A portable, durable memory store for AI agents that saves markdown notes with YAML frontmatter — no database required. Files are git-friendly and Obsidian-compatible.
Core Memory Operations
Create (
create_memory): Store facts, decisions, or context as structured notes with metadata (title, category, tags, status, aliases, author)Retrieve (
get_memory): Fetch a complete memory by ID, including its full markdown body and frontmatterAppend (
append_memory): Add content to an existing memory while preserving current content and updating the timestampUpdate (
update_memory): Patch metadata fields or replace the markdown body of an existing memoryArchive (
archive_memory): Soft-delete by marking a memory as archived without removing the fileDelete (
delete_memory): Permanently remove a memory
Search & Browse
Search (
search_memory): Full-text, relevance-ranked search across title, aliases, tags, description, and body; supports metadata filters (category, status, tags, author)List (
list_memories): Browse memory metadata in bulk without loading full content; filter by status, category, and tags
Organization & Maintenance
Build index (
build_memory_index): Generate a human-readable markdown index (index.md), optionally grouped by categoryLoad index (
load_memory_index): Retrieve the generated index, with an option to refresh before loadingRebuild/repair (
rebuild_memory): Fix missing or malformed frontmatter, apply/normalize[[wikilinks]]from titles and aliases, and rebuildindex.md/index.yaml; supports dry-run mode
Key characteristics: memories are plain markdown files organized into category-based directories, support [[wikilinks]] for cross-referencing, and work with any MCP-compatible AI agent (Claude, OpenAI, local models, etc.).
Provides a portable memory server for AI agents, enabling persistent memory storage and retrieval for OpenAI agents through the Model Context Protocol.
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., "@memex-mcp create a memory about the project architecture decision"
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.
Smriti MCP
A portable memory server for AI agents, built for the Model Context Protocol (MCP).
Smriti stores durable memories as plain markdown files with YAML frontmatter. This keeps your data readable, git-friendly, and easy to inspect outside any single agent runtime.
Features
Framework agnostic: Works with any MCP-compatible agent (Claude, OpenAI, local models, etc.)
Durable & portable: All memories stored as plain markdown files—no database required
Git-friendly: Version control your memories alongside your code
Search & filter: Full-text search, filtering by tags, categories, and status
Relationship tracking: Use
[[wikilinks]]to connect related memoriesMemory index: Auto-generate markdown indexes of your entire memory store
Archive & organize: Hierarchical organization with categories and status tracking
Related MCP server: mem-persistence
Installation
Smriti MCP is published on PyPI as smriti-mcp.
With pip
Install into your current Python environment:
pip install smriti-mcpThen verify the CLI is available:
smriti-mcp --helpWith uv
Install Smriti as a persistent command-line tool:
uv tool install smriti-mcpOr run it directly without a separate install:
uvx smriti-mcp --helpFrom source for development
git clone https://github.com/deepak-bhardwaj-ps/smriti-mcp.git
cd smriti-mcp
pip install -e .Quick Start
1. Run the server locally
smriti-mcp server --memory-root ~/.smriti/memoryBy default, Smriti uses ~/.smriti/memory. You can override it with:
export SMRITI_MEMORY_ROOT="$HOME/.smriti/memory"
smriti-mcp serverIf you prefer uvx, run the server with:
uvx smriti-mcp server --memory-root ~/.smriti/memory2. Configure in your MCP client
Claude Desktop with pip or uv tool install (~/.config/claude_desktop_config.json):
{
"mcpServers": {
"smriti": {
"type": "stdio",
"command": "smriti-mcp",
"args": ["server", "--memory-root", "~/.smriti/memory"]
}
}
}Claude Desktop with uvx:
{
"mcpServers": {
"smriti": {
"type": "stdio",
"command": "uvx",
"args": ["smriti-mcp", "server", "--memory-root", "~/.smriti/memory"]
}
}
}Then restart Claude Desktop and Smriti will be available as a tool.
Available Tools
Core Operations
Tool | Description |
| Create a new durable markdown memory with metadata |
| Retrieve a memory by ID and return its full content |
| Add content to the end of an existing memory |
| Patch metadata or replace memory content |
| Permanently remove a memory |
| Agent-friendly write API that records a trace and can create, append, or update |
| Create, append, or update a memory from reviewed trace content |
Search & Browse
Tool | Description |
| Full-text search across title, tags, categories, and body. Returns ranked results |
| Browse memory metadata without loading full content. Filter by status, category, tags |
Organization
Tool | Description |
| Mark a memory as archived (soft delete) |
| Generate a markdown index of all memories for easy browsing |
| Fix frontmatter, apply/normalize wikilinks from titles and aliases, and rebuild indexes |
| Load the generated index as markdown |
Memory Format
Each memory is stored as a markdown file with YAML frontmatter:
---
id: project/Example Architecture Decision
title: Example Architecture Decision
category: project
tags:
- architecture
- decision
status: active
short_description: Decided to use async/await pattern
created_at: "2026-06-05T10:30:00+10:00"
updated_at: "2026-06-05T10:30:00+10:00"
---
## Background
We needed to handle concurrent requests efficiently.
## Decision
Use async/await with asyncio for I/O-bound operations.
## Consequences
- Improved throughput for concurrent operations
- Need to manage event loop carefully in multi-threaded contexts
See also: [[Async Migration]], [[Performance Metrics]]Metadata Fields
id: Unique identifier (auto-generated from category + title, or custom)
title: Human-readable title
category: Organizational category (becomes directory in file structure)
tags: Array of searchable tags
status:
active,archived, or custom statusshort_description: Brief summary (used in indexes)
created_at: ISO 8601 timestamp
updated_at: ISO 8601 timestamp
memory_type, confidence, salience, scope, source_agent: Optional agent memory metadata used for filtering and recall
File Structure
~/.smriti/memory/
├── project/
│ ├── Example Architecture Decision.md
│ ├── Async Migration.md
│ └── Performance Metrics.md
├── research/
│ └── LLM Benchmarks.md
├── decisions/
│ └── Use Postgres.md
└── index.mdSmriti keeps default filenames aligned with memory titles so Obsidian-style wikilinks like
[[API Rate Limiting Strategy]] resolve to API Rate Limiting Strategy.md.
When you run rebuild_memory, Smriti can automatically add missing wikilinks and normalize
alias links. It matches longer titles and aliases first and only links whole phrases, so
Durable Memory is preferred over durable, and able is not linked inside durable.
Usage Examples
Create a memory
from smriti_mcp.store import MemoryStore
store = MemoryStore("~/.smriti/memory")
result = store.create_memory(
{
"title": "API Rate Limiting Strategy",
"category": "decisions",
"tags": ["api", "performance"],
"short_description": "Decided on sliding window rate limiting",
},
content="We chose sliding window over token bucket because...",
)
# Returns: {"id": "decisions/API Rate Limiting Strategy", ...}Remember with precise metadata
result = store.remember(
content="User prefers markdown-first durable memory with no mandatory vector database.",
id="preferences/Markdown First Memory",
meta={
"title": "Markdown First Memory",
"category": "preferences",
"memory_type": "preference",
"short_description": "Preference for markdown-first durable memory.",
"source_agent": "codex",
"confidence": "high",
},
mode="create",
)remember treats supplied meta as authoritative. If short_description is omitted,
Smriti leaves it omitted instead of deriving a partial summary from the body. In auto
mode, Smriti only appends to an existing memory when there is a strong deterministic
match such as the same title; use id with append or update mode for explicit writes.
Search memories
results = store.search_memory(
query="rate limiting",
include_content=False, # Just metadata
)
for result in results:
print(f"{result['id']}: {result['title']}")List memories with filters
active_decisions = store.list_memories(
status="active",
category="decisions",
)
for memory in active_decisions:
print(f"{memory['title']} ({memory['status']})")Rebuild and repair memories
result = store.rebuild_memory(
fix_frontmatter=True,
apply_wikilinks=True,
group_by_category=True,
)
print(result["wikilinks"]["links_added"])Running Tests
# Install test dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/ -v
# Run integration tests only
pytest tests/test_smriti_mcp_integration.py -vAll tests pass, including full MCP stdio round-trip integration tests.
Architecture
MemoryStore: Core storage engine with markdown file I/O
Server: MCP server exposing tools to agents
CLI: Command-line interface for running the stdio server
Frontmatter: YAML metadata parsing and generation
The package has zero external database dependencies and works with Python 3.10+.
Roadmap
Web UI for browsing memories
Multi-user support with authentication
Memory graph visualization
Sync to cloud storage (S3, GCS)
Memory embeddings for semantic search
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch (
git checkout -b feature/my-feature)Add tests for new functionality
Ensure all tests pass (
pytest tests/ -v)Submit a pull request
License
MIT License - see LICENSE file for details.
Author
Created by Deepak Bhardwaj.
See Also
Available Tools
11 toolsappend_memoryA
Append new markdown to an existing memory while preserving its current content and updating the modified timestamp.
Inputs: id (required), content (required). Returns: object
archive_memoryA
Mark a memory as archived without deleting its markdown file.
Inputs: id (required). Returns: object
build_memory_indexB
Build or refresh the human-readable markdown memory index at index.md.
Inputs: group_by_category. Returns: object
create_memoryA
Create a durable markdown memory for facts, decisions, preferences, or project context that should survive beyond the current chat.
Inputs: meta (required), content (required), id. Returns: object
delete_memoryA
Permanently delete a memory note by id.
Inputs: id (required). Returns: object
get_memoryB
Retrieve a memory note by id and return its complete markdown with YAML frontmatter.
Inputs: id (required). Returns: result
list_memoriesA
List memory metadata for browsing or filtering without returning full note bodies. Use search_memory when you need relevance ranking.
Inputs: category, status, tags, limit. Returns: object
load_memory_indexB
Load the generated markdown memory index, optionally refreshing it first.
Inputs: refresh. Returns: result
rebuild_memoryA
Repair and rebuild the memory store: optionally fix frontmatter, apply or normalize wikilinks from memory titles and aliases using longest matches first, then rebuild index.md and index.yaml.
Inputs: apply_wikilinks, fix_frontmatter, group_by_category, dry_run. Returns: object
search_memoryA
Search durable memories with relevance ranking over title, aliases, tags, path, description, and body terms.
Inputs: query (required), limit, filters, include_content. Returns: object
update_memoryA
Patch memory metadata and optionally replace the full markdown body. Use append_memory when adding incremental observations.
Inputs: id (required), meta, content. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: create, read, update, delete, archive, search, and index operations are all separate, with no overlap.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_memory, search_memory), making them predictable and easy to understand.
11 tools is appropriate for a memory management server, covering essential operations without unnecessary bloat.
The tool set provides full lifecycle management: create, read (get, list, search), update (append, update, rebuild), delete, archive, and index operations, with no obvious gaps.
Maintenance
Related MCP Connectors
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
One memory, every AI. A shared, user-owned markdown memory your AI clients read and write over MCP.
An MCP memory server. One memory your agents share — across models, devices and apps.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA portable MCP server providing a shared intelligent memory system for any MCP-compatible AI tool, enabling storage, retrieval, extraction, and governance of memories across sessions.MIT
- AlicenseNot gradedqualityDmaintenancePersistent memory MCP server that stores and retrieves memories in Markdown files, enabling shared context across multiple AI agents with hybrid search and deduplication.MIT
- AlicenseAqualityBmaintenanceMCP server for persistent, cross-session, local-first memory for AI agents, storing memories as Markdown files with SQLite indexing for hybrid search.24Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides a file-first personal memory layer for AI agents, enabling them to store and retrieve memories as markdown files with an SQLite index. The MCP server offers read-only search by default, with optional write tools for manual memory addition and conflict resolution.2 npmMIT