ai-memory-template

# Tool List > Cross-AI tool shared long-term memory — Let your AI tools share the same brain without complex environments — Visualized memory [](LICENSE)   --- ## What is this Do you use multiple AI tools simultaneously? They each have independent context windows and are unaware of what the others have done. **ai-memory-template** provides a shared memory library for all AI tools through **MCP (Model Context Protocol)**. Knowledge written by one AI can be read by all AI tools. ### Comparison: With vs Without Memory | Scenario | Without shared memory | With shared memory | |------|------------------|------------------| | You tell AI you use VS Code and prefer Python | Next conversation, AI asks again | AI automatically reads from memory and remembers | | WorkBuddy fixes a bug | Codex doesn't know, may repeat troubleshooting | Codex checks memory and knows | | Project architecture decisions | Context lost after conversation | Permanently recorded on project page, maintained across conversations | | Multi-AI collaboration | Independent, information fragmented | Shared knowledge base | --- ## Core Advantages ### 1. Zero External Dependencies Only Python 3.10+ and a `pip install mcp` are required. No database, container, or cloud service needed. ### 2. Pure File Storage All memories are stored as **pure Markdown files**. This means: - You can open and edit directly with **Obsidian** - Use **git** for version control - Use **grep** for full-text search - Modify with any text editor - Backup by copying a folder ### 3. Visualized Memory Network Since all memories are in **Markdown + double-link ([[Wiki Link]])** format, you can directly open the memory directory with **Obsidian** and obtain a complete knowledge graph visualization: - **Graph View** — The link network of all notes is clearly visible, showing which projects are most closely related and which notes are hub nodes - **Local Graph** — Select a note and view its out-links and back-links - **Orphan Detection** — Obsidian automatically highlights notes without links, complementary to the `memory_orphans` tool ``` Obsidian Graph View effect (text representation): Operations a ↑ ┌──—————— Project a ———————──┐ │ ↑ │ │ User Profile ←──── Memory Index │ ↓ │ └──———————— Project b ———————─┘ ↓ Recent Work Dynamics ``` The `memory_graph` and `memory_orphans` MCP tools can also query link relationships directly in AI conversations, independent of Obsidian. ### 4. Cross-Platform + Cross-AI MCP is an open protocol. This service can connect to any MCP-supported client: - **Codex CLI** - Current conversation - **Claude Desktop** - Anthropic desktop client - **WorkBuddy** - Domestic AI assistant - **Cursor** - AI code editor - Any tool supporting MCP stdio transmission ### 5. 3 Built-in Automatic Mechanisms Reduce manual workload, automatically processed when AI writes: - **Auto-tagging** — Automatically infer tags from content, 30+ mapping rules covering common domains ``` Input: "Wrote a Docker deployment script in Python" Output tags: [deploy, python] ``` - **Auto-linking** — Detect known note titles in content, automatically add bi-directional links ``` Input: "Referenced User Profile and Memory Index content" Output links: [User Profile, Memory Index] ``` - **Auto-archiving** — Cold tier entries automatically moved to `.archive/` directory, with summary stubs left in place ### 6. Cross-Process Concurrency Safety File locks prevent data overwrite when multiple AI tools write simultaneously. 15-second timeout automatically takes over expired locks. --- ## Quick Start ### Requirements - Python 3.10+ - Install `mcp` package: `pip install mcp` ### One-Click Installation AI assistant quick start: ```bash Please help me deploy the ai-memory-template MCP project. Project address: https://github.com/dpkg-s/ai-memory-template Steps: 1. Clone or download the project to your local machine 2. Install dependencies (pip install mcp) 3. Create a memory directory for me 4. Configure MCP settings for my operating system (Windows / Mac / Linux) and enable auto-start 5. Finally, tell me how to verify if it's working normally ``` macOS / Linux: ```bash curl -sSL https://raw.githubusercontent.com/dpkg-s/ai-memory-template/main/install.sh | bash ``` Windows PowerShell: ```bash irm https://raw.githubusercontent.com/dpkg-s/ai-memory-template/main/install.ps1 | iex ``` The installation script will: 1. Install `mcp` Python package 2. Create a memory directory at `~/ai-memory/` 3. Copy initial template files 4. Print MCP configuration for each platform ### Manual Installation ```bash git clone https://github.com/dpkg-s/ai-memory-template.git cd ai-memory-template pip install mcp bash install.sh # Linux/macOS .\install.ps1 # Windows ``` ### Configure AI Tools Add the configuration output by the installation script to the MCP configuration of the corresponding AI tool: **Codex CLI** — `~/.codex/config.toml` ```toml [mcp_servers] [mcp_servers.ai-memory] command = "/usr/bin/python3" args = ["/home/you/ai-memory/server.py"] ``` **Claude Desktop** — `claude_desktop_config.json` ```json { "mcpServers": { "ai-memory": { "command": "/usr/bin/python3", "args": ["/home/you/ai-memory/server.py"] } } } ``` **WorkBuddy** — `~/.workbuddy/mcp.json` ```json { "mcpServers": { "ai-memory": { "type": "stdio", "command": "/usr/bin/python3", "args": ["/home/you/ai-memory/server.py"] } } } ``` > Complete configuration templates can be found in the [`setup/`](setup/) directory. --- ## Customization ### Modify Memory Directory Path Set environment variable: ```bash export AI_MEMORY_DIR=/path/to/your/memory python server.py ``` ### Customize Auto-tagging Rules Edit the `_TAG_AUTO_MAP` dictionary in `server.py`, approximately 30 keyword → tag mappings. Add or remove as needed. --- ## Technology Stack | Layer | Technology | Description | |------|------------|------------| | Protocol | **MCP (Model Context Protocol)** | Open standard, stdio transmission, JSON-RPC 2.0 | | Framework | **FastMCP (Python SDK)** | MCP server framework, automatically handles protocol layer | | Storage | **Markdown + JSON Frontmatter** | Each memory as a .md file, metadata stored in frontmatter | | Cache | **Python dict (memory)** | Entry cache + access count cache, invalidated on write | | Lock | **File lock (PID + timestamp)** | Cross-process mutex, 15-second timeout | | Search | **Keyword matching + multi-field scoring** | Title/tag/abstract/content weighted sorting | | Graph | **Regular expression parsing [[Wiki Link]]** | Obsidian-compatible double-link syntax, directly visualizable with Obsidian graph view | | Audit | **Full-library scan + heat analysis** | Health statistics + cold/hot data identification | ### Architecture Diagram ``` ┌─────────────────────────────────────────────────────┐ │ AI Client Layer │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │ │ │ Codex │ │ Claude │ │ WorkBuddy │ │ │ │ CLI │ │ Desktop │ │ (and any MCP │ │ │ │ │ │ │ │ compatible tool)│ │ │ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │ │ │ │ │ │ ├───────┴─────────────┴─────────────────┴─────────────┤ │ MCP Protocol Layer (stdio) │ │ JSON-RPC 2.0 over stdin/stdout │ ├──────────────────────┬──────────────────────────────┤ │ server.py (MCP Server) │ │ ┌────────┬────────┬────────┬────────┬───────────┐ │ │ │ Read │ Write │ Search │ Graph │ Stats │ │ │ │ │ │ │ │ Archive │ │ │ └────────┴────────┴────────┴────────┴───────────┘ │ │ ┌──────────────────────────────────────────────┐ │ │ │ Infrastructure │ │ │ │ File lock │ Entry cache │ Access count cache │ Log │ │ │ │ Auto-tag │ Auto-link │ Auto-archive │ │ │ └──────────────────────────────────────────────┘ │ └──────────────────────┬──────────────────────────────┘ │ ┌──────────────────────┴──────────────────────────────┐ │ Storage Layer (File System) │ │ ┌──────────────────────────────────────────────┐ │ │ │ D:/ai-memory/ (or any directory) │ │ │ │ ├── User Profile.md │ │ │ │ ├── Recent Work Dynamics.md │ │ │ │ ├── Project _xxx.md │ │ │ │ ├── Memory Index.md │ │ │ │ └── .archive/ │ │ │ │ └── Archived entries.md (summary stub left) │ │ │ └──────────────────────────────────────────────┘ │ │ ↑ You can also directly open this directory with Obsidian │ └─────────────────────────────────────────────────────┘ ``` --- ## 16 Tool Complete Instructions ### Read/Write Operations | Tool | Signature | Function | |------|-----------|---------| | `memory_write` | `(title, content, tags?, source?, summary?, tier?)` | Write or update memory. Auto-tagging + auto-linking + auto-archiving | | `memory_read` | `(title)` | Read by title. Access count cache in memory, batch write back after 10 accesses | | `memory_search` | `(keyword, tag?)` | Keyword search, can specify tag filtering | | `memory_delete` | `(title)` | Delete memory (hard delete) | ### Advanced Queries | Tool | Function | |------|---------| | `memory_graph(title)` | Display out-links and back-links graph of specified note | | `memory_orphans()` | Find **孤立笔记** (notes not referenced by any other note) | | `memory_smart_search(query, tag?, limit?)` | **Multi-field weighted search**: title ×10, tag ×4, abstract ×3, content ×1, with timeliness scoring | | `memory_list(tag?, limit?, tier?)` | List all memory summaries | | `memory_stats()` | **Health statistics**: quantity of each tier, top 10 access frequency, updates in last 7/30/90 days, top 10 popular tags, number of孤立笔记 | ### Maintenance Operations | Tool | Function | |------|---------| | `memory_archive(title)` | Archive: move content to `.archive/`, leave summary stub in place | | `memory_archive_old(days=90)` | Batch archive entries not updated for N days (skip core pages) | | `memory_batch_tag(old_tag, new_tag)` | Rename tags across the library | | `memory_batch_tier(target_tier, min_score?, max_score?)` | Batch adjust tier by heat score | | `memory_heat_suggest()` | Scan the library and provide tier upgrade/downgrade suggestions | ### Audit Tools | Tool | Function | |------|---------| | `memory_audit()` | Full-library scan, grouped by type, suggestions for organization | | `memory_index_draft()` | Automatically generate memory index draft | --- ## Project Structure ``` ai-memory-template/ ├── README.md # This document ├── server.py # MCP server (single file, ~1300 lines) ├── install.ps1 # Windows one-click installation script ├── install.sh # Linux/macOS one-click installation script ├── setup/ # MCP configuration templates for each platform │ ├── codex.toml │ ├── claude.json │ └── workbuddy.json ├── template/ # Initial memory files (out-of-the-box) │ ├── Recent Work Dynamics.md │ ├── User Profile.md │ ├── Memory Index.md │ └── Memory Write Format Specification.md └── rules/ # Specifications for AI writing └── Memory Write Format Specification.md ``` --- ## License MIT