aiaml by m2de - MCP Server

AI Agnostic Memory Layer (AIAML)

A simple local memory system for AI agents that provides persistent storage and retrieval using the Model Context Protocol (MCP).

Quick Start

MCP Client Setup (Claude Desktop, etc.)

Add this to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

Minimal setup (uses defaults):

{
  "mcpServers": {
    "aiaml": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/m2de/aiaml.git", "aiaml"]
    }
  }
}

Customised setup

{
  "mcpServers": {
    "aiaml": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/m2de/aiaml.git", "aiaml"],
      "env": {
        "AIAML_MEMORY_DIR": "/path/to/your/aiaml-data",
        "AIAML_ENABLE_SYNC": "true",
        "AIAML_GITHUB_REMOTE": "git@github.com:yourusername/your-memory-repo.git",
        "AIAML_LOG_LEVEL": "INFO"
      }
    }
  }
}

That's it! No installation required - uvx will automatically handle dependencies.

Requirements

Python 3.10+
uv (install with brew install uv or pip install uv)

Alternative Setup Methods

If you prefer a local installation:

{
  "mcpServers": {
    "aiaml": {
      "command": "uv",
      "args": ["--directory", "/path/to/aiaml", "run", "aiaml"]
    }
  }
}

Memory Tools

The server provides three MCP tools for AI agents:

remember - Store new memories with metadata
think - Search memories by keywords
recall - Retrieve full memory details by ID

Memory Format

Memories are stored as markdown files:

---
id: abc12345
timestamp: 2024-01-15T10:30:00.123456
agent: claude
user: marco
topics: [programming, python]
---

Memory content goes here.

Configuration

Environment Variables

All configuration is done through environment variables (either in MCP config or .env file):

Variable	Default	Description
`AIAML_MEMORY_DIR`	`~/.aiaml`	Base directory for all AIAML data
`AIAML_ENABLE_SYNC`	`true`	Enable Git synchronization
`AIAML_GITHUB_REMOTE`	`none`	Git remote URL for sync (optional)
`AIAML_LOG_LEVEL`	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`AIAML_MAX_SEARCH_RESULTS`	`20`	Maximum search results returned
`AIAML_GIT_RETRY_ATTEMPTS`	`3`	Git operation retry attempts
`AIAML_GIT_RETRY_DELAY`	`1.0`	Delay between git retries (seconds)

Directory Structure

When you set AIAML_MEMORY_DIR="/path/to/aiaml", the following structure is created:

/path/to/aiaml/
├── files/        # Memory files (*.md)
├── backups/      # Backup files
├── temp/         # Temporary files
├── locks/        # File locks
└── .git/         # Git repository (if sync enabled)

Local `.env` File

If running locally, you can create a .env file:

AIAML_MEMORY_DIR="/path/to/your/aiaml-data"
AIAML_ENABLE_SYNC="true"
AIAML_GITHUB_REMOTE="git@github.com:yourusername/your-memory-repo.git"
AIAML_LOG_LEVEL="INFO"

Testing

# Run all tests
python3 test.py

# Run individual tests
python3 test_core_functionality.py
python3 test_mcp_integration.py

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

Keep it simple - this project focuses on reliable local memory storage for AI agents.

License

MIT License - see LICENSE file for details.