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., "@Memo MCP How was my mood last week?"
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.
Memo MCP is a local Model Context Protocol (MCP) server that provides flexible search capabilities over personal memo and journal entries using Retrieval-Augmented Generation (RAG) with indexing and GPU support for faster embeddings. Retrieve past context for new conversations anytime.
With Memo MCP, you can ask about past events from your journal entries (e.g. How has my mood changed in the past 3 months?), and the LLM can also be aware of past discussed events and point it without being asked if it judges appropriate to the current discussion. You can also add new entries automatically about the current day.
For privacy and safety, I recommend personal journaling with not-so-sensitive data in your personal computer. If you decide to use it with "external" models such as Claude, Gemini etc., be careful about any personal, sensitive data and information.
Related MCP server: joa
Journal processing: Ask natural language questions such as "How did I do at work this year?", "How was my mood overall last week? How does it compare to last month?" to LLMs and get relevant excerpts from your journal
GPU Acceleration: Optional GPU support for faster embedding generation
Multiple Vector Stores: Support for local ChromaDB, FAISS and simple in-memory storage. Will add Qdrant in the future.
Date Filtering: Filter search results by year, month, or specific dates
MCP Integration: Works seamlessly with Claude Desktop, Cline, and other MCP-compatible LLM clients
Automatic Indexing: Automatically builds and maintains search indices for your journal entries
Clone repository and install dependencies with uv:
cd memo-mcp
uv syncPrepare your memo data (Instructions) structure appropriately. Example to create a sample entry:
# Create the expected directory structure
mkdir -p data/memo/2025/01
# Add your journal entries in markdown format
# Example: data/memo/2025/01/15.md
echo "# January 15th, 2025
Had a great day at work today. Finished the project ahead of schedule..." > data/memo/2025/01/15.mdSet up Memo MCP on your client MCP configuration file (Instructions).
Restart your client and you're ready to use!
If you wish to customize "advanced" settings, such as top_k, chunk_size, etc., keep reading the documentation.
If you wish to run the RAG as a Claude agent (without MCP), make sure to instruct it to run the RAG CLI as per Instructions.
The Memo MCP expects the memo and journal entries to be stored in a folder using the pattern [year]/[month]/[day].md:
data/memo/
├── 2024/
│ ├── 01/
│ │ ├── 07.md
│ │ ├── 15.md
│ │ ├── 28.md
│ │ └── ...
│ ├── 08/
│ │ └── ...
│ └── ...
├── 2025/
│ ├── 07/
│ │ ├── 01.md
│ │ └── ...
│ └── ...
└── ...It is recommended to store it inside data/memo, as it is the default folder being monitored by the MCP server, and it is already added to .gitignore for safety.
A sample data folder can be found in data/memo_example. It contains multiple sample journal entries you can use to test the MCP querying.
In case you wish to use a different memo/journal data directory instead of the recommended data/memo path, you can modify it:
Update .gitignore: Add your custom path to prevent Git tracking:
# Add to .gitignore
path/to/my_custom_memo_repo/Modify MCP Configuration: Update the data_path in your MCP server configuration file or environment variables to point to your custom location.
Update server.py: Ensure the RAG indexer points to your new data directory by changing DATA_DIR path to your custom folder in memo_mcp/mcp/server.py.
Always ensure your memo/journal data folder is included in .gitignore to prevent accidentally committing personal information to version control.
Memo/journal data is indexed to speed up search and retrieval. A recommendation is to set up your agent to rebuild the index everyday to ensure that new entries are included in the search results -- Rebuilding the index periodically guarantees that all recent journal entries are properly integrated into your searchable personal archive.
The Memo MCP server provides these tools for LLM interaction:
add-memo: Add a new memo entry to your journal
content (required): The memo entry content
date (optional): Date for the entry in YYYY-MM-DD format (defaults to today)
search-journal: Search through journal entries
query (required): Your search question
top_k (optional): Number of results (1-20, default: 366)
date_filter (optional): Filter by date (e.g., "2025", "2025-01")
get-journal-stats: Get memo dataset stats
rebuild-journal-index: Rebuild the search index
force (optional): Force rebuild even if index exists
You can integrate the Memo MCP to multiple services, such as Cline in Visual Studio Code, Claude Desktop, or any code editor of your choice.
Add the MCP server: Add to your Cline MCP Config file ([...]/cline_mcp_settings.json), changing [PATH TO BASE DIRECTORY] to the directory containing the cloned memo-mcp repo:
{
"mcpServers": {
"memo-mcp": {
"disabled": false,
"timeout": 60,
"type": "stdio",
"command": "uv",
"args": [
"--directory",
"[PATH TO BASE DIRECTORY]/memo-mcp",
"run",
"memo-mcp"
]
}
}
}Restart Cline and start asking questions about your journal, or ask it to write a new entry data too.
Add the MCP server:
Add to your Claude Desktop config (~/claude_desktop_config.json). You can optionally set up envionment variables:
{
"mcpServers": {
"memo-mcp": {
"command": "uv",
"args": [
"--directory",
"[PATH TO BASE DIRECTORY]/memo-mcp",
"run",
"memo-mcp"
],
"env": {
"MEMO_DATA_ROOT": "/path/to/your/journal/data"
}
}
}
}Restart Claude Desktop and start asking questions about your journal, or ask it to write a new entry data too.
Once integrated, you can ask your LLMs things such as:
- "How did I feel about work this year?"
- "Show me entries about my vacation in July this year"
- "What goals did I set for myself in 2025?"
- "How was my mental health last month?"
- "How many times did I forget to get groceries last week?"Using Gemini 2.5 Pro, with the sample (fictional) data provided in data/memo_example:
> How did I feel about work this year?
Based on your journal entries from 2025, it seems you've had a dynamic and transformative year at work, marked by significant highs and challenging lows.
**Early Success and Satisfaction (January):**
The year started on a very positive note. You received a long-awaited promotion, which brought a feeling of overwhelming relief and gratitude. You celebrated this achievement and felt a deep sense of things "falling into place." Later that month, you had a highly productive day where you tackled your entire to-do list, leaving you with a satisfying sense of accomplishment.
**Struggles and Burnout (March):**
By March, your momentum seemed to wane. You described feeling stuck, struggling to find your rhythm, and your brain feeling like it was "moving through molasses." This culminated in a difficult team meeting where you felt you had nothing meaningful to contribute, highlighting a period of professional frustration.
**A Major Setback and a Shift in Perspective (June):**
June brought a significant challenge with a "disastrous" job interview. Despite your preparation, the experience left you cringing. However, this failure became a turning point. It prompted you to question whether you were on the right career path and if the "corporate ladder" was what you truly wanted.
**Finding a New Groove (November):**
Towards the end of the year, things took a positive turn. A new workflow system you implemented began to pay off, making your work more seamless and efficient. You adopted new productivity techniques, like time-blocking, which helped you feel more in control and less overwhelmed. This not only improved your own work life but also enabled you to help a colleague who was struggling with similar issues, bringing you a sense of satisfaction.
**Overall Themes:**
Throughout the year, your feelings about work have been a rollercoaster. You've experienced the thrill of success, the weight of burnout, and the sting of failure. However, each of these experiences seems to have contributed to a deeper understanding of what you want from your career. You've learned the importance of not just working hard, but also working smart, and you've begun to question traditional notions of success in favor of finding a more sustainable and fulfilling path.
The Memo MCP system uses Retrieval Augmented Generation (RAG) to perform queries over your daily entries.
Multiple vector search DBs are supported: ChromaDB and FAISS local servers. A simple in-memory vector database can also be used for testing and simple operations.
The RAG (Retrieval-Augmented Generation) system creates vector embeddings of your memo and journal content, allowing for flexible queries such as "How did I handle stress last month?" or "What were my thoughts on career changes?" without manually scanning through files, surfacing relevant entries based on broader meanings rather than just keyword matches.
Memo MCP automatically detects if there's any GPU or MPS (Apple M1/M2...) available for performance optimisation, significantly improving the speed of embedding generation.
The default vector database is ChromaDB. You can also choose FAISS or a simple in-memory implementation. All of these servers will run locally in your computer.
Other settings can be configured via environment variables or by modifying the configuration in memo_mcp/mcp/server.py:
config = RAGConfig(
vector_store_type="chroma", # "chroma", "faiss", or "simple"
data_root=Path("data/memo"), # Path to your journal files
use_gpu=True, # Enable GPU acceleration
cache_embeddings=True, # Cache embeddings for faster startup
chunk_size=2000, # Text chunk size for processing
default_top_k=5, # Default number of search results
similarity_threshold=0.3 # Minimum similarity for results
)MEMO_DATA_ROOT: Override the default data directory
MEMO_USE_GPU: Enable/disable GPU usage ("true"/"false")
MEMO_EMBEDDING_MODEL: Custom embedding model name
MEMO_RAG_LITE: Enable resource-constrained mode ("true"/"false")
[TODO: a comprehensible diagram showing how the RAG provides the "logic" for the retrieval, using the MCP as an interface to connect it as tools for the LLMs.]
If you want to experiment with the RAG querying system without the aid of MCP plugins -- for example, with a Claude agent --, you can run task rag -- [query] or task rag -- [query] [optional parameters]. For full description of the optional parameters, run task rag-help.
# Show help and usage examples
task rag-helpusage: main.py [-h] [-k TOP_K] [-d PATH] [-v {chroma,faiss,simple}] [-r] query
Query memo journal entries using RAG (Retrieval-Augmented Generation)
positional arguments:
query Natural language search query (e.g., 'how did I feel
about work this year?')
options:
-h, --help show this help message and exit
-k TOP_K, --top-k TOP_K
Number of top results to return (default: 366)
-d PATH, --data-dir PATH
Path to memo data directory with YYYY/MM/DD.md
structure (default: data/memo)
-v {chroma,faiss,simple}, --vector-store {chroma,faiss,simple}
Vector store backend: chroma (persistent), faiss
(fast), simple (in-memory) (default: chroma)
-r, --rebuild Force rebuild of the search index (use after adding
new entries)
Examples:
"how did I feel about work this year?"
"last time I started a hobby" -k 10
"my thoughts on AI" --rebuild --vector-store faiss
"travel plans" -d /path/to/custom/data
The tool uses semantic search to find relevant journal entries based on your query.
Results are ranked by similarity score, and include file paths and content previews.Run RAG queries directly from the command line using the task rag command:
# Run a query
task rag -- "how did I feel about work this year?"
# Query with custom number of results
task rag -- "last time I started a hobby" -k 10
# Rebuild index and search
task rag -- "my thoughts on AI" --rebuild
# Use custom data directory
task rag -- "travel plans" -d /path/to/custom/data
# Use different vector store backend
task rag -- "productivity tips" --vector-store faissYou can also try writing your own simple script to make use of the rag codebase:
from memo_mcp.rag import create_rag_system, RAGConfig
from pathlib import Path
# Create and initialize RAG system
config = RAGConfig(data_root=Path("data/memo"))
rag = await create_rag_system(config)
# Search your journal
results = await rag.query("productivity tips", top_k=3)
for result in results:
print(f"File: {result['metadata'].file_name}")
print(f"Text: {result['text'][:200]}...")
print("---")
await rag.close()You can try running the MCP local server in your CLI:
uv run memo-mcpor
task serverTo run the development tasks, use the following commands:
task listtask: Available tasks for this project:
* check: Run code quality checks
* clean: Clean up generated files
* format: Format code using ruff
* install-dev: Install development dependencies
* rag: Run RAG query over journal entries (usage: task rag -- "your query"). For help with the parameters, run: task rag-help
* rag-help: Show RAG CLI help and usage examples
* server: Run the MCP server in the CLI
* test: Run tests with pytest
* test-cov: Run tests with coverage report
* test-data: Test data structure validation
* test-data-summary: Show data structure summaryMake sure to always run check, format and test.
task format
task check
task testThis project is licensed under the MIT License - see the LICENSE file for details.
memo_mcp/mcp/server.py is built on top of the Model Context Protocol
Add a new memo entry to your journal collection
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The memo entry content | |
| date | No | Date for the entry (YYYY-MM-DD format). If not provided, uses today's date. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It only states the action without disclosing behavioral traits such as permission requirements, idempotency, or side effects. The agent lacks information about what happens on duplicate dates or content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence without redundant information. However, it could be expanded slightly to include critical behavioral details while remaining concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description is adequate but lacks behavioral context. It does not cover what the agent should expect after execution, such as confirmation or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any extra meaning beyond what the schema already provides for parameters. It does explain how the date parameter defaults to today, but that information is already in the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add', the object 'memo entry', and the location 'journal collection'. It effectively distinguishes itself from siblings like 'get-journal-stats', 'rebuild-journal-index', and 'search-journal', which serve different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference sibling tools or conditions under which this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics about your journal database (document count, chunks, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It clearly indicates a read-only operation ('get statistics'), implying no side effects. For a simple stats tool, this is transparent enough, though it does not mention response format or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence containing all necessary information. No wasted words, front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides examples of the statistics returned. It is sufficient for understanding the tool's purpose but could be more comprehensive about the full set of outputs or structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so per the baseline rule, 4 is appropriate. The description adds value by listing example statistics (document count, chunks), helping the agent understand what the tool returns beyond an empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves statistics about the journal database, specifically mentioning document count and chunks. This unambiguously identifies the resource and output, and it is distinct from sibling tools like add-memo (creation), rebuild-journal-index (maintenance), and search-journal (query).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide guidance on when to use this tool versus alternatives. It implies usage for obtaining general database statistics, but it lacks explicit when-not conditions or mentions of alternative tools. This is adequate for a straightforward tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild the journal search index (use if you've added new entries)
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force rebuild even if index exists |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it rebuilds the index but does not disclose potential side effects like time consumption or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. Every element adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one optional boolean and no output schema, the description provides adequate purpose and usage context. It could mention what triggers the rebuild or potential impacts, but it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (force) with a clear schema description, which covers its semantics. The tool description adds no further meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb "Rebuild" and the resource "journal search index", with a usage hint. It distinguishes from siblings like add-memo and search-journal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use when adding new entries, providing clear context. It does not list exclusions or alternatives, but sibling tools imply those.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search through journal entries using RAG. Perfect for questions like 'how did I do at work this year?' or 'what were my thoughts on AI?'
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query or question about your journal entries | |
| top_k | No | Number of results to return (default: 366) | |
| date_filter | No | Optional date filter (e.g., '2025', '2025-01', '2025-01-15') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'RAG' but does not disclose potential delays, authentication needs, or whether the search is destructive or read-only. The description is too vague on behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that convey the core purpose and example usage with no filler. Every word adds value, earning a high score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has three parameters and no output schema, the description covers the search functionality and provides examples. However, it lacks details on return format, ordering, or the date_filter's exact behavior, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so the description adds little beyond the schema. It includes example usage which provides context, but does not elaborate on parameter details or constraints beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'journal entries using RAG', making the tool's purpose unambiguous. The example questions ('how did I do at work this year?') further clarify usage, and the purpose is distinct from siblings like add-memo and get-journal-stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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, specifically for asking questions about journal entries. However, it does not explicitly state when not to use it or mention alternatives, though siblings are listed separately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.4.0add-memoget-journal-statsrebuild-journal-indexsearch-journalEach tool addresses a distinct function: adding, searching, managing index, and viewing statistics. There is no overlap in their purposes.
All tools follow a consistent verb-noun pattern with hyphens (e.g., add-memo, search-journal), making names predictable and easy to understand.
With 4 tools, the set is well-scoped for a lightweight journaling server, covering essential operations without unnecessary bloat.
Core actions (add, search, stats, maintenance) are present, but missing read/update/delete operations for individual memos, which may require agents to use search as a workaround.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
MemoryOracle - 10 agent memory tools: vector store, recall, summarization, redaction.
Universal persistent memory and knowledge retrieval layer for AI agents and LLMs.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/milasd/Memo-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
