# 🧠 agentmem

[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://github.com/Josan88/agentmem)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP Compliant](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io)

**`agentmem`** is a high-performance, local-first persistent contextual memory & knowledge-base engine designed specifically for **AI coding agents** (Claude Code, OpenAI Codex, Cursor, Antigravity) and **Model Context Protocol (MCP)** servers.

---

## 🌟 Why `agentmem`?

AI agents frequently forget critical architectural decisions, environment setup constraints, and session conclusions across chat restarts. `agentmem` acts as a zero-latency, local memory bank that seamlessly indexes and retrieves codebase knowledge without ballooning prompt token context.

### Key Features

- ⚡ **Zero-Latency Local Storage**: File-backed JSON key-value & structured memory store.
- 🔌 **Native MCP Integration**: Plug directly into Claude Desktop, Cursor, or any MCP-compatible agent.
- 🏷️ **Context Tagging & Retrieval**: Store memories tagged by scope (`architecture`, `bugfix`, `decision`, `setup`, `todo`).
- 💻 **Intuitive CLI**: Query, insert, export, and manage context directly from the terminal.
- 🛡️ **Privacy First**: 100% local execution — no external API calls required for storage.

---

## 🚀 Quick Start

### 1. Installation

```bash
pip install agentmem
```

### 2. CLI Usage

```bash
# Remember an architectural decision
agentmem add "Used SQLite/JSON for agentmem storage to guarantee single-file zero-dependency portability" --tag architecture

# Query stored memories
agentmem search "SQLite"

# List all memories in the current workspace
agentmem list

# Clear memories
agentmem clear
```

---

## 🔌 Using as an MCP Server

`agentmem` includes support for Model Context Protocol integration. Add the following to your `claude_desktop_config.json` or editor settings:

```json
{
  "mcpServers": {
    "agentmem": {
      "command": "agentmem",
      "args": ["mcp"]
    }
  }
}
```

---

## 🤝 Contributing

We welcome community contributions! Please check out [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding conventions, and pull request workflows.

1. Fork the Repository
2. Create a Feature Branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to Branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

Distributed under the MIT License. See [LICENSE](LICENSE) for more details.