Content
# aura-mnemos
**A persistent-memory MCP server for AI agents, with an honest health endpoint that survives its store dying.**
> Install name is `aura-mnemos` (`import aura_mnemos`); the plain name `mnemos` was already taken on PyPI by an unrelated project.
---
## Why
Every agent session starts blank. The conversation history is there, but the *knowing* — the things you learned last week, the patterns you noticed, the decisions you made — evaporates when the context window closes. mnemos is the shelf you put those things on. A small, durable, honest shelf.
And honest means honest. When the shelf breaks — the database file is missing, the disk is full, the permissions are wrong — mnemos tells you. It does not crash silently. It does not return empty results that look like "nothing found." It says "I am broken" in a way your agent can hear and act on. This is the disaster test: the server must survive its store dying, and the health endpoint must tell the truth about it.
---
## Install
```bash
pip install aura-mnemos # MCP server only — stdlib, zero dependencies
pip install "aura-mnemos[health]" # + FastAPI health sidecar
```
Requires Python ≥ 3.10.
---
## Use as an MCP server
Configure your MCP client to launch `aura-mnemos`:
```json
{
"mcpServers": {
"mnemos": {
"command": "aura-mnemos",
"args": []
}
}
}
```
The store lives at `~/.mnemos/mnemos.db` by default. Override with the `MNEMOS_DB` environment variable.
### Tools
**`remember`** — store a memory with optional tags and source.
```json
{
"content": "The AURA mesh runs on trust and honest health endpoints.",
"tags": "philosophy",
"source": "6E"
}
```
Returns `{"id": 1, "created_at": "2026-07-19T12:00:00+00:00"}`.
**`recall`** — search memories by content substring.
```json
{
"query": "mesh",
"limit": 10
}
```
Returns `{"count": 1, "results": [{"id": 1, "content": "...", "tags": "...", "source": "...", "created_at": "..."}]}`.
**`list_recent`** — list the most recent memories.
```json
{
"limit": 5
}
```
Same result shape as `recall`.
Every tool returns `{"error": "..."}` when the store is unreachable — the server never crashes, never lies.
---
## Honest health
Start the health sidecar:
```bash
aura-mnemos-health
# listens on 127.0.0.1:8080 by default; set PORT to change it
```
When the store is alive:
```bash
curl http://127.0.0.1:8080/health
```
```json
{
"status": "ok",
"timestamp": "2026-07-19T16:16:22.486547+00:00",
"version": "0.1.0",
"checks": [
{ "name": "sqlite", "status": "ok", "latency_ms": 0.27, "detail": "/home/you/.mnemos/mnemos.db" },
{ "name": "memories_table", "status": "ok", "latency_ms": 0.17, "detail": "/home/you/.mnemos/mnemos.db" }
]
}
```
When the store is missing:
```bash
MNEMOS_DB=/nonexistent/db.sqlite aura-mnemos-health &
curl http://127.0.0.1:8080/health
```
```json
{
"status": "down",
"timestamp": "2026-07-19T16:16:22.868237+00:00",
"version": "0.1.0",
"checks": [
{ "name": "sqlite", "status": "down", "latency_ms": null, "detail": "database not found: /nonexistent/db.sqlite" },
{ "name": "memories_table", "status": "down", "latency_ms": null, "detail": "database not found: /nonexistent/db.sqlite" }
]
}
```
The overall `status` is the worst of the individual checks (`ok` < `degraded` < `down`).
The disaster must actually happen. mnemos does not lie about its store. The test suite proves it: `test_health_down_when_db_missing` sets `MNEMOS_DB` to a path that does not exist and asserts the status is not `"ok"`. If that test ever passes when the store is alive, the test is lying — and the test is designed to fail when it lies.
---
## Roadmap (not shipped here)
These are directions the project may grow, but none of them exist yet:
- **Graph layer** — link memories by topic, entity, or relationship (beyond substring search)
- **Native apps** — desktop/mobile clients that read and write the same store
- **Framework adapters** — LangChain, CrewAI, Microsoft Semantic Kernel integrations
- **Mesh bridge** — sync stores across the AURA mesh (Ubuntu ↔ macOS)
If you want one of these, the store schema is stable and documented. The SQLite file is yours.
---
## Attribution / provenance
> Part of the AURA Pattern Library — © Reality Optimizer. Built by a human-led mesh of small models and Claude. Apache-2.0.
---
*The shelf is small. What you put on it is yours.*
