Alice

<!-- mcp-name: io.github.samrusani/alice-memory -->

The continuity layer for AI agents.

uvx alice-memory install --data-dir ~/.alice
uvx alice-memory demo --vault ~/Notes --data-dir ~/.alice-demo

alice-memory doctor prints sources, then candidates.

Alice is a local-first memory service that lets AI agents resume interrupted work, track open loops, recall decisions with provenance, and improve when corrected — instead of re-reading transcripts or trusting opaque summaries.

A LongMemEval_s receipt of 81.2% mean over three independent full runs (80.8 / 81.0 / 81.8; 404-409 of 500) was measured 2026-07-18/19 on the published v0.12.0 tag with the privileged store_chunks harness. That path reads chunks straight from the store. No MCP tool offers it, and it is not the product path. pack_excerpts is the product-path mode and is not yet a published score. Per-question evidence for all three runs, the reader/judge/embedding configuration, and the reproduction script are committed to this repo. Multi-session is the weakest category at roughly 63%. The 30-question abstention subset is noisy across runs (76.7 / 90.0 / 83.3) and should not be quoted to one decimal. The earlier single run of 79.4% (397/500) from 2026-07-07 is retained as evidence.

Agents connect over MCP, HTTP API, or CLI. Humans stay in control: agent writes land as policy-checked commits or reviewable proposals, and a local review console is where memory gets approved, corrected, or forgotten. That review boundary is a feature, not a limitation — it is what makes the memory trustworthy enough to act on.

How Alice compares

Most agent memory tools — mem0, Zep, Letta, and similar — focus on extracting facts from conversations and retrieving them later. That solves recall, and they do it well. Alice focuses on continuity: it stores typed continuity objects (decisions, open loops, resumption briefs) alongside plain memories; source-backed answers trace to the evidence that was supplied; and writes are review-governed, so an agent cannot silently promote a bad extraction into durable truth. Explicit commits may legitimately have no source reference. If you mainly need conversational fact recall, those tools are solid choices. If your agents need to resume work, honor past decisions, and explain why they believe something, that is what Alice is built for.

Alice is a layer, not a lock-in: it runs happily alongside other memory tools, and plenty of stacks will want both — a fact-extraction memory for conversational recall and Alice for governed continuity.

What Alice stores

• Memories — typed, revisioned facts with trust classification and, when evidence was supplied, provenance links to that source evidence.
• Decisions — what was decided, when, and what superseded it.
• Open loops — blockers, waiting-fors, and follow-ups that agents can query, create, and close.
• Resumption briefs — "here is where work stopped, and what should happen next" for a project or thread.
• Provenance and audit — source-backed memories identify their supplied sources; reviews and corrections preserve their audit chain. Explicit commits may legitimately have no source reference.

Corrections are first-class: when a memory is corrected or superseded, future recall reflects the correction and the explanation chain shows why.

Quickstart

The fastest path is the packaged runtime from PyPI. Python 3.12+ and nothing else, no Docker, Node, or Postgres.

uvx alice-memory install --data-dir ~/.alice

That writes Claude Desktop, Claude Code, Cursor, and OpenClaw MCP config. Claude Code and Cursor also get a SessionStart hook so the next session can inject the brief. Hermes is opt-in: add --host hermes. The command writes host config. It does not import a vault.

OpenClaw can also add the server in one line, which probes before saving:

openclaw mcp add alice --command uvx --arg alice-memory --arg mcp --arg --data-dir --arg ~/.alice

Or paste this into a host that still wants a file. There is no DATABASE_URL:

{
  "mcpServers": {
    "alice": {
      "command": "uvx",
      "args": ["alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]
    }
  }
}

To serve MCP yourself after install:

uvx alice-memory mcp --data-dir ~/.alice
# or: pip install alice-memory && alice-memory mcp --data-dir ~/.alice

OpenClaw prefixes MCP tool names with the server name, so alice_recall reaches the model as alice__alice_recall.

Skill packs

Optional, and useful once Alice is connected. agent-skills/ holds a ready-made instruction pack for each host, telling the agent when to reach for memory rather than leaving it to guess. Copy the directory, not the file:

cp -R agent-skills/openclaw/alice-project-memory ~/.openclaw/skills/
cp -R agent-skills/hermes/alice-memory ~/.hermes/skills/

Both hosts load <skill-name>/SKILL.md and read the frontmatter description to decide when the skill applies. A skill grants no tools on its own; it tells an agent how to use the ones the MCP server already provides.

SQLite mode is the single-agent path and the one most agents should use: it serves the default three tools for one user. Capture, the pack, and review are on the full surface (ALICE_MCP_FULL_TOOLS=1). Boundaries are listed in known limitations.

Install note: the PyPI package is alice-memory. The name alice-core on PyPI belongs to an unrelated project.

Full stack (Postgres + review console)

For the full experience — Postgres/pgvector, the web review console, and core memory scheduler workflows — run from a repo checkout. Requirements: Python 3.12+, Node 20+, pnpm, Docker, Git.

git clone https://github.com/samrusani/AliceMemory.git
cd AliceMemory
make setup
make migrate
make doctor
make dev

• make setup creates .env files from checked-in examples and installs Python and web dependencies.
• make migrate starts local services (Postgres via Docker) and runs database migrations.
• make doctor runs readiness checks and applies safe fixes.
• make dev runs the API on port 8000 and the web review console on port 3000.

Open the review console at http://localhost:3000/vnext. The detailed walkthrough — demo data, smoke checks, first memory — is in the alpha quickstart.

Connect an agent

MCP

Point any MCP-capable agent or IDE at the Alice server. For the packaged SQLite runtime, use the uvx config from the Quickstart above. For the full Postgres stack from a checkout:

{
  "mcpServers": {
    "alice": {
      "command": "/ABSOLUTE/PATH/TO/AliceMemory/.venv/bin/python",
      "args": ["-m", "alicebot_api.mcp_server"],
      "cwd": "/ABSOLUTE/PATH/TO/AliceMemory",
      "env": {
        "DATABASE_URL": "postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot",
        "ALICEBOT_AUTH_USER_ID": "00000000-0000-0000-0000-000000000001"
      }
    }
  }
}

The default MCP surface is three tools:

• alice_memory_commit — record one fact as durable, immediately recallable memory. This is the verb for ordinary memory, including when the user has not asked the agent to remember. Policy-checked: committed, confirmation-required, review-required, or rejected
• alice_recall — search memory (full-text plus vector, fused ranking; hard-scopable by thread, task, project, person, time, and memory type). Also returns matching passages from captured documents under sources, with an excerpt to read and quote; results are facts Alice asserts, sources are material the user imported, and the same scope fence applies to both
• alice_resume — resumption brief for a project or thread

The other eight core tools (alice_capture, alice_context_pack, alice_open_loops, alice_recent_decisions, alice_memory_review, alice_memory_correct, alice_memory_manage, alice_explain) stay defined and become listed and callable when ALICE_MCP_FULL_TOOLS=1. Capture stores a source; candidates stay unsearchable as memories. Import is a source. Commit is a fact.

Calling directly from a human client (Claude Desktop, an IDE)? alice_memory_commit needs only title and canonical_text — no identity fields. Agent integrations declare agent_id and agent_type; see agent integration.

The write verbs follow one contract. Outcomes, audit guarantees, and honest boundaries per verb are documented in the Memory Operations Protocol. Removed backing services no longer have MCP tools. Retained long-tail memory tools require ALICE_MCP_LEGACY_TOOLS=1 and append to whatever core set is enabled; exactly alice_task_brief, alice_task_brief_show, and alice_task_brief_compare additionally require ALICE_LEGACY_SURFACES=1. All legacy tools require a deliberately keyless local-operator deployment; a server bound with ALICE_AGENT_API_KEY exposes only the enabled core set.

Custom agents calling the HTTP API authenticate with per-agent API keys. See agent integration.

Embeddings

Semantic search works with any OpenAI-compatible embeddings endpoint — Ollama, LM Studio, or OpenAI:

ALICE_EMBEDDINGS_BASE_URL=http://localhost:11434/v1
ALICE_EMBEDDINGS_MODEL=nomic-embed-text
ALICE_EMBEDDINGS_API_KEY=            # only if the endpoint requires one

Search fuses Postgres full-text results with pgvector 0.8+ (iterative HNSW) similarity using reciprocal-rank fusion. If no embedding endpoint is configured, search degrades to full-text only and says so explicitly in the retrieval trace.

Status

v0.16.0 is the latest published release and remains the install, checksum, and release-note baseline (the v0.13.0 tag was never published; superseded). Its tag, release record, and published artifacts are immutable. v0.12.0 shipped the Phase 3 structural refactor with Structure only. Zero behavior change. It splits oversized HTTP, store, contract, MCP, and CLI modules behind stable imports and entrypoints. The published v0.11.0 runtime narrows the default product to the agent interface and retrieval/memory core. Alice is a public-alpha, pre-1.0 project. What that means in practice:

• Local-first, single-user. One operator, one machine (or one headless server reached over SSH).
• Review-governed writes. Agents propose or commit through policy; outcomes are commit, confirm, review, or reject. The review console is the trust boundary for durable memory.
• No hosted service. There is no cloud offering yet; you run Alice yourself.
• No channels or bundled chat runtime. Telegram, hosted administration, chief-of-staff/chat/model-pack features, and the public /v0/responses chat endpoint are not part of the current product. Retained /v1/runtime/invoke still uses internal durable response-job/provider machinery.
• No managed OAuth or automatic polling. Temporary manual-token Gmail and Calendar compatibility is unmounted by default be