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

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:

{
  "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.

{
  "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.

{
  "query": "mesh",
  "limit": 10
}

Returns {"count": 1, "results": [{"id": 1, "content": "...", "tags": "...", "source": "...", "created_at": "..."}]}.

list_recent — list the most recent memories.

{
  "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:

aura-mnemos-health
# listens on 127.0.0.1:8080 by default; set PORT to change it

When the store is alive:

curl http://127.0.0.1:8080/health

{
  "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:

MNEMOS_DB=/nonexistent/db.sqlite aura-mnemos-health &
curl http://127.0.0.1:8080/health

{
  "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.