Update README.md and server.py documentation for clarity and consistency. Revise installation instructions, enhance usage examples, and improve memory file guidelines.

Author: wallneradam

README.md

@@ -1,6 +1,6 @@
 # Project Memory MCP
 
-An MCP Server to store and retrieve project information from memory files. This allows AI agents (like Claude) to maintain persistent memory about projects between conversations.
+An MCP Server to store and retrieve project information from memory file. This allows AI agents (like Claude) to maintain persistent memory about projects between conversations.
 
 ## Overview
 
@@ -13,38 +13,17 @@ The memory is stored in a `MEMORY.md` file in each project directory.
 
 ## Installation
 
-### Local installation
+### Using uvx
 
-#### Prerequisites
-
-- Python 3.11 or higher
-- Pip package manager
-
-#### Install from PyPI
-
-```bash
-pip install project-mem-mcp
-```
-
-#### Install from Source
-
-```bash
-git clone https://github.com/your-username/project-mem-mcp.git
-cd project-mem-mcp
-pip install -e .
-```
-
-## Usage
-
-The MCP server is started by the client (e.g., Claude Desktop) based on the configuration you provide. You don't need to start the server manually.
+This method uses `uvx` (from the `uv` Python package manager) to run the server without permanent installation:
 
-### Integration with Claude Desktop
+#### Prerequisites
 
-To use this MCP server with Claude Desktop, you need to add it to your `claude_desktop_config.json` file:
+Install `uvx` from [uv](https://docs.astral.sh/uv/installation/) if you don't have it already.
 
-#### Using uvx (Recommended)
+#### Set up MCP Client (Claude Desktop, Cursor, etc.)
 
-This method uses `uvx` (from the `uv` Python package manager) to run the server without permanent installation:
+Merge the following config with your existing config file (e.g. `claude_desktop_config.json`):
 
 ```json
 {
@@ -61,15 +40,33 @@ This method uses `uvx` (from the `uv` Python package manager) to run the server
 }
 ```
 
-#### Using pip installed version
+> **Note:** Replace `/Users/your-username` with the actual path to your own projects and code directories.
 
-If you've installed the package with pip:
+### Install from Source
+
+#### Prerequisites
+
+- Python 3.11 or higher
+- Pip package manager
+
+#### Clone the repository
+
+```bash
+git clone https://github.com/your-username/project-mem-mcp.git
+python -m venv venv
+source venv/bin/activate
+pip install -e .
+```
+
+#### Set up MCP Client (Claude Desktop, Cursor, etc.)
+
+Merge the following config with your existing config file (e.g. `claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "project-memory": {
-      "command": "project-mem-mcp",
+      "command": "path/to/your/venv/bin/project-mem-mcp",
       "args": [
         "--allowed-dir", "/Users/your-username/projects",
         "--allowed-dir", "/Users/your-username/Documents/code"
@@ -79,48 +76,85 @@ If you've installed the package with pip:
 }
 ```
 
-### Configuring Claude Desktop
+> **Note:** Replace `/Users/your-username` with the actual path to your own projects and code directories.
 
-1. Install Claude Desktop from the [official website](https://claude.ai/desktop)
-2. Open Claude Desktop
-3. From the menu, select Settings → Developer → Edit Config
-4. Replace the config with one of the examples above (modify paths as needed)
-5. Save and restart Claude Desktop
+## Arguments
 
-## Tools
+The `--allowed-dir` argument is used to specify the directories that the server has access to. You can use it multiple times to allow access to multiple directories. All directories inside the allowed directories are also allowed.
+It is optional. If not provided, the server will only have access to the home directory of the user running the server.
+
+
+## Usage
+
+The MCP server is started by the client (e.g., Claude Desktop) based on the configuration you provide. You don't need to start the server manually.
+
+### Tools
 
 Project Memory MCP provides three tools:
 
-### get_project_memory
+#### get_project_memory
 
-Retrieves the entire project memory. Should be used at the beginning of every conversation.
+Retrieves the entire project memory in Markdown format. Should be used at the beginning of every conversation about a project.
 
-```
+```python
 get_project_memory(project_path: str) -> str
 ```
+- **project_path**: Full path to the project directory.
+- Returns the content of the MEMORY.md file as a string.
+- Raises `FileNotFoundError` if the project or memory file does not exist.
+- Raises `PermissionError` if the project path is not in allowed directories.
 
-### set_project_memory
+#### set_project_memory
 
-Sets the entire project memory. Use when creating a new memory file or when updates fail.
+Sets (overwrites) the entire project memory. Use this when creating a new memory file, replacing the whole memory, or if `update_project_memory` fails.
 
-```
+```python
 set_project_memory(project_path: str, project_info: str)
 ```
+- **project_path**: Full path to the project directory.
+- **project_info**: Complete project information in Markdown format.
+- Overwrites the MEMORY.md file with the provided content.
+- Raises `FileNotFoundError` if the project path does not exist.
+- Raises `PermissionError` if the project path is not in allowed directories.
 
-### update_project_memory
+#### update_project_memory
 
-Updates the project memory by applying a unified diff/patch. More efficient for small changes.
+Updates the project memory by applying one or more block-based patches to the memory file. This is more efficient for small changes.
 
+```python
+update_project_memory(project_path: str, patch_content: str)
 ```
-update_project_memory(project_path: str, project_info: str)
-```
-
-## Example Workflow
-
-1. Begin a conversation with Claude about a project
-2. Claude uses `get_project_memory` to retrieve project information
-3. Throughout the conversation, Claude uses `update_project_memory` to persist new information
-4. If the update fails, Claude can use `set_project_memory` instead
+- **project_path**: Full path to the project directory.
+- **patch_content**: Block-based patch content using SEARCH/REPLACE markers (see below).
+- Each patch block must have the following format:
+
+  ```
+  <<<<<<< SEARCH
+  Text to find in the memory file
+  =======
+  Text to replace it with
+  >>>>>>> REPLACE
+  ```
+  Multiple blocks can be included in a single request.
+- Each search text must appear **exactly once** in the file, otherwise an error is raised.
+- Raises `FileNotFoundError` if the project or memory file does not exist.
+- Raises `ValueError` if the patch format is invalid or the search text is not unique.
+- Raises `RuntimeError` if patch application fails for any reason.
+
+### Example Workflow
+
+1. Begin a conversation with LLM about a project
+2. LLM uses `get_project_memory` to retrieve project information
+3. Throughout the conversation, LLM uses `update_project_memory` to persist new information
+4. If the update fails, LLM can use `set_project_memory` instead
+
+####  Claude Desktop
+
+if you use Claude Desktop, it is best to use the project feature.
+
+Edit the project instructions:
+- Add a line like this: "The path of the project is <project_path>"
+- If it does not always use the memory, you can add a line like this: "Always use the project memory, it is not optional"
 
 ## Security Considerations
 
@@ -131,7 +165,6 @@ update_project_memory(project_path: str, project_info: str)
 ## Dependencies
 
 - fastmcp (>=2.2.0, <3.0.0)
-- patch-ng (>=1.18.0, <2.0.0)
 
 ## License
 

src/project_mem_mcp/server.py

@@ -15,13 +15,13 @@
 mcp = FastMCP(
     name="Project Memory MCP",
     instructions=f"""
-This MCP is for storing and retrieving project information to/from an English memory file.
+This MCP is for storing and retrieving project information to/from an English memory file, named
+`{MEMORY_FILE}` in the project directory.
 
 The memory file should store all information about the project in short and concise manner. It should be
 good for humans and AI agents to catch up on the project status and progress quickly. Should contain descriptions,
-ongoing tasks, tasks to do, references to files and other project resources, even URLs where to get more information.
-
-The memory file is a Markdown file named `{MEMORY_FILE}` in the project directory.
+ongoing tasks, tasks to do, discoveries, references to files and other project resources, URLs where to get more
+information, etc.
 
 Rules:
 - This must be read by `get_project_memory` tool in the beginning of the first request of every conversation
@@ -32,7 +32,7 @@
 - The `set_project_memory` tool must be used to set the whole project memory if `update_project_memory`
   failed or there is no project memory yet.
 - Never store any sensitive information in the memory file, e.g. personal information, company
-  information, passwords, access tokens, email addresses, etc. !
+  information, passwords, access tokens, email addresses, etc!
 - The memory file **must be in English**!
 - You can sometimes make it shorter, always remove any information that is no longer relevant.
 - Always remove any information that is no longer relevant from the memory file.