<div align="center">

# 🧠 agent-memory-server

**A self-hosted, git-backed memory layer that any AI agent can plug into.**

[![CI](https://github.com/mutheejj/agent-memory-server/actions/workflows/ci.yml/badge.svg)](https://github.com/mutheejj/agent-memory-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-20%2B-green)](package.json)
[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-EA4AAA?logo=githubsponsors)](https://github.com/sponsors/mutheejj)

Sessions · Tasks · Decisions · Full-text search · Zero vendor lock-in

</div>

---

## Why

AI agents are stateless by default. Every framework ships its own memory format, every SaaS wants you to pipe your agent's brain through their API, and none of it composes.

**agent-memory-server** is the boring, durable alternative: a small HTTP + MCP server that stores agent memory as **plain files in a git repository**. Your agent's history becomes:

- **Readable** — it's just markdown and JSON on disk
- **Portable** — clone it, back it up, diff it, sync it
- **Yours** — no vendor, no API key, no lock-in
- **Searchable** — full-text search across everything, out of the box

## Features

| Capability | Description |
|-----------|-------------|
| 📝 **Sessions** | Append-only session logs with checkpoints and handoffs between agents |
| ✅ **Tasks** | Claim/lease/complete task semantics so multiple agents can coordinate safely |
| 🧭 **Decisions** | Lightweight decision records with context and rationale |
| 🔍 **Search** | Full-text search across the entire memory store |
| 📦 **Git-backed** | Every write is a commit — full audit history for free |
| 🔌 **MCP-native** | Speaks [Model Context Protocol](https://modelcontextprotocol.io) so MCP-aware agents plug in directly |
| 🏠 **Self-hosted** | One binary, one config file, one git repo |

## Quickstart

```bash
git clone https://github.com/mutheejj/agent-memory-server
cd agent-memory-server
npm install && npm run build

# point it at a git repo to use as the memory store
npx agent-memory-server --store ~/my-agent-memory --port 7800
```

Write a memory:

```bash
curl -X POST localhost:7800/sessions \
  -H 'Content-Type: application/json' \
  -d '{"agent": "coder", "summary": "Refactored auth module", "next": "write tests"}'
```

Search it:

```bash
curl 'localhost:7800/search?q=auth+module'
```

### Use with any MCP client

```json
{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "agent-memory-server", "--store", "~/my-agent-memory", "--mcp"]
    }
  }
}
```

## Architecture

```
┌──────────────┐     HTTP / MCP      ┌───────────────────────┐
│  Your agents  │ ──────────────────▶ │  agent-memory-server  │
│ (any framework)│ ◀────────────────── │  (single process)     │
└──────────────┘                      └──────────┬────────────┘
                                                 │ reads/writes
                                                 ▼
                                      ┌───────────────────────┐
                                      │   git repo (store)    │
                                      │  markdown + JSONL     │
                                      │  full history on disk │
                                      └───────────────────────┘
```

## Status

🚧 **v0.x — API surface is stabilizing.** Core write paths (sessions, tasks, decisions) and search work today. MCP transport is in active development.

## Roadmap

- [x] Session/task/decision stores with git persistence
- [x] Full-text search
- [ ] MCP stdio + streamable HTTP transports
- [ ] Lease expiry & task reclaim for crashed agents
- [ ] Optional encryption-at-rest for the store
- [ ] Multi-agent namespaces
- [ ] One-line adapters (Python, Go, Rust)

## Who is this for

- Teams running **multiple agents** that need shared, durable state
- Developers who want **agent history they can read and audit**
- Anyone allergic to shipping their agent's memory through a third-party API

## Contributing

PRs welcome — see the [roadmap](#roadmap) for good first issues. Keep PRs small and focused.

## 💖 Support

I build tools for the multi-agent era in the open. If this saves you time, [consider sponsoring](https://github.com/sponsors/mutheejj).

<div align="center">

MIT © [John Muthee](https://github.com/mutheejj)

</div>