alice-memory 0.9.0

Alice: the continuity layer for AI agents. Local-first memory with provenance, open loops, resumption, and review-governed writes.

Alice

The continuity layer for AI agents.

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.

It scores 64.6% on LongMemEval, the long-term-memory benchmark — in the same range as the best published commercial results — and the full per-question evidence, methodology, and reproduction script are committed to this repo so anyone can verify it. Open source, local-first, MIT-licensed.

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; every answer carries explainable provenance back to source evidence; and writes are review-governed, so an agent cannot silently promote a bad extraction into durable truth. 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. On LongMemEval, Alice scores 64.6% with the official judge protocol, in the same range as the best published results in the category, with full methodology and per-question evidence in the repo. Knowledge-update questions score 74.4% — the correction and supersession machinery doing its job.

What Alice stores

• Memories — typed, revisioned facts with trust classification and provenance links to 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 — every memory can explain which sources, reviews, and corrections produced it.

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. It serves the eleven core MCP tools against a single local SQLite file:

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

MCP client config (Claude Desktop, IDEs) — note there is no DATABASE_URL:

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

SQLite mode is the trial and single-agent path: it serves the eleven core tools for one user, and memory review happens through alice_memory_review / alice_memory_correct instead of the web console. 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 — web review console, scheduler, legacy surfaces — run from a repo checkout. Requirements: Python 3.12+, Node 20+, pnpm, Docker, Git.

git clone https://github.com/samrusani/AliceBot.git
cd AliceBot
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 docs/alpha/quickstart.md.

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/AliceBot/.venv/bin/python",
      "args": ["-m", "alicebot_api.mcp_server"],
      "cwd": "/ABSOLUTE/PATH/TO/AliceBot",
      "env": {
        "DATABASE_URL": "postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot",
        "ALICEBOT_AUTH_USER_ID": "00000000-0000-0000-0000-000000000001"
      }
    }
  }
}

The core MCP surface is eleven tools:

• alice_capture — submit new information as source-backed, reviewable memory
• alice_memory_commit — write an explicit "remember this" memory through policy: committed, confirmation-required, review-required, or rejected
• alice_recall — search memory (full-text plus vector, fused ranking; filterable by memory type and project)
• alice_resume — resumption brief for a project or thread
• alice_context_pack — scoped context bundle for a task, with an enforced token budget
• alice_open_loops — list and manage open loops
• alice_recent_decisions — recent decision log
• alice_memory_review — inspect items pending review
• alice_memory_correct — propose a correction to an existing memory
• alice_memory_manage — confirm, undo, or forget a committed memory, audit trail intact
• alice_explain — provenance and trust explanation for a memory

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 docs/alpha/agent-integration.md.

The write verbs follow one contract — outcomes, audit guarantees, and honest boundaries per verb are documented in the Memory Operations Protocol. The legacy long-tail tool surface stays available behind ALICE_MCP_LEGACY_TOOLS=1 for existing integrations.

Custom agents calling the HTTP API authenticate with per-agent API keys. See docs/alpha/agent-integration.md.

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 (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

Alice is pre-1.0. 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 OAuth connectors. Capture paths are local files, explicit API/CLI/MCP calls, and agent output ingestion — not automatic syncing of external accounts.
• No automatic capture from arbitrary conversation. Durable memory comes from explicit commits, reviewable proposals, or captured sources, never from silent transcript mining.

Docs

• Quickstart walkthrough
• Agent integration
• MCP tools
• Custom agent guide
• Known limitations
• Security and privacy
• Architecture
• Roadmap
• Changelog

Contributing

Issues, integrations, importers, and eval contributions are welcome. See CONTRIBUTING.md.

Security

If you discover a security issue, follow the process in SECURITY.md.

License

MIT — see LICENSE.