ariadne

# ariadne

**English** · **[Українська](README.uk.md)**

A **native, local-first, multilingual memory server** for
[Codex](https://github.com/openai/codex),
[Claude Code](https://claude.com/claude-code), and any MCP client.
[Go](https://go.dev/) +
[Qdrant](https://qdrant.tech) + [bge-m3](https://huggingface.co/BAAI/bge-m3) —
no Docker, no cloud, no API keys.

Purpose-built for private coding-agent memory: a small native appliance rather
than a hosted, multi-tenant memory platform. The default path is offline and
cross-lingual, with observable retrieval cost and no account dependency.

[![Release](https://img.shields.io/github/v/release/mclaut/ariadne)](https://github.com/mclaut/ariadne/releases/latest)
[![CI](https://github.com/mclaut/ariadne/actions/workflows/ci.yml/badge.svg)](https://github.com/mclaut/ariadne/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-11120f.svg)](LICENSE)

**[Project site](https://mclaut.github.io/ariadne/)** ·
**[Hugging Face Space](https://huggingface.co/spaces/mclaut/ariadne)** ·
**[Latest release](https://github.com/mclaut/ariadne/releases/latest)**

Built as a replacement for embedded vector-DB memory backends that crash or
starve under several concurrent MCP sessions. ariadne is a **server**: one
Qdrant handles concurrent writes natively, so the whole single-writer /
lock-starvation class simply doesn't exist.

## What's New in v0.8.0

**Scoped append-only memory lifecycle.** Identical text may exist independently
in different projects and rooms. A move writes the destination record first and
retains the original as superseded history. Session capture records actual event
and capture times separately and assigns stable opaque source lineage. Daily
consolidation saves durable memories first, then archives source diaries by
metadata; it never deletes them. A first zero-output review remains active as
`candidate_empty` and needs a later confirming pass after a grace period before
archival. Normal recall hides archived/superseded records, while exact-ID lookup
or `include_archived: true` provides an explicit audit path.

**Conservative historical ranking.** Qdrant still supplies the dense+BM25 RRF
candidate set. A small bounded second pass adds source quality, explicit
temporal intent, and context-size signals. Old decisions and gotchas do not
decay merely because they are old; recency applies only when the query asks for
the latest/current/history-aware answer, and metadata cannot override a
material semantic lead.

**Non-destructive, observable maintenance.** Memfile sync skips unchanged source
revisions before embedding, imports changed revisions before marking older
chunks `superseded`, and preserves original observation timestamps; vanished
sources become `orphaned`, not deleted. Consolidation is batch- and
context-bounded, validates model output, and retains source diaries when any
promotion fails. The runner retries transient failures with capped backoff,
records append-only activity, and exposes failed, partial, stuck, or stale state
in status and the tray. Backup rotation archives older snapshots.

**Deterministic regression evaluation.** `go run ./cmd/eval` executes the
multilingual coding-memory ranking suite in `evaluation/coding-memory.json`
without touching Qdrant or Ollama.

## Previously in v0.7.0

**Exact retrieval and immediate durable memory.** `memory_recall` now accepts an
exact scoped-content `id`, so agents can retrieve and verify one memory without an
embedding call or approximate ranking. Semantic recall can also be scoped by
both project (`wing`) and category (`room`).

The shared Ariadne skill now requires agents to save completed release,
deployment, migration, audit, incident-resolution, and verified-status reports
to `reference` immediately when the outcome becomes known. This is proactive:
the agent does not wait for SessionEnd, PreCompact, daily consolidation, or a
separate “remember this” command. Decisions and hard-won gotchas follow the same
immediate-save discipline.

Token metrics separate source-backed measurement from unknown delivery instead
of treating every legacy recall as negative savings:

- **measured saved/net** — source-backed context benefit after attributed cost;
- **attribution coverage** — the share of observed recall cost with provenance;
- **unattributed** — visible legacy/manual delivery with no invented benefit.

The tray shows measured savings, coverage, recall count, and unattributed cost.
`ariadnectl metrics` and JSON retain the complete observed-cost counters.

```json
{
  "id": "2704862554782470108"
}
```

## Previously in v0.6.0

**Automatic diary distillation.** SessionEnd capture writes one concise,
local-model diary memory per substantive session. Daily maintenance revisits
diary entries older than 24 hours, groups them by project and day, and promotes
durable decisions with rationale, verified gotchas, critical constraints, and
important open risks. Source chronology remains archived for audit instead of
being discarded.

The process is fail-safe and append-only: Ariadne creates a due weekly Qdrant
snapshot before archival, saves every distilled memory, then marks the source
group archived. A first empty pass stays active for later confirmation, and a
failure leaves the source group active for retry. The summary endpoint remains
local-only unless remote capture is explicitly enabled.

Preview or run it manually:

```bash
ariadnectl consolidate --before 24h --dry-run
ariadnectl maintenance  # memfile sync + consolidation, with bounded retries
ariadnectl consolidate --before 24h  # consolidation only
ariadnectl requeue-empty --dry-run  # inspect records archived by the legacy one-pass empty policy
```

The installer schedules the 04:30 daily memory maintenance job on macOS and
Linux. A failed stage is retried up to three times with bounded exponential
backoff; partial import failures return non-zero and block consolidation.
systemd uses `Persistent=true`; a loaded launchd calendar agent receives one
catch-up start after the Mac wakes when a scheduled time was missed. The tray
shows the latest outcome, warns when maintenance failed, remains partial, is
stuck, or is older than 36 hours, and offers **Run maintenance now**. Output is
written to `~/.ariadne/logs/maintenance.log`; append-only outcomes live in
`~/.ariadne/state/activity.jsonl`.

## Previously in v0.5.0

- **Explicit Windows client integration** — the installer detects Claude Code
  and Codex CLI, then asks which one to configure. It never creates settings for
  an absent client and non-interactive installs require an explicit choice.
- **Core-only and configure-later modes** — install the local Ariadne stack with
  `-CoreOnly`, then connect Claude or Codex later with `-ConfigureClients`.
  Consent-gated updates preserve existing client configurations unchanged.
- **Physical and VM preflight** — PowerShell now reports Windows, CPU, RAM, disk,
  and machine type; enforces the default models' minimum resources; gives
  Proxmox/KVM CPU guidance; and directly executes `qdrant.exe --version` before
  registering the service.

## What's New in v0.4.0

- **Local token-efficiency metrics** — Ariadne estimates confirmed savings,
  recall overhead, and signed net context benefit for automatic and MCP recalls. Totals are
  available through `ariadnectl metrics`, its JSON form, and the tray menu.
- **Content-free accounting** — only numeric counters and opaque event hashes
  are stored locally. Repeated hook delivery counts as overhead without claiming
  the same represented session context twice.

## What's New in v0.3.1

- **Clean Windows prerequisite repair** — the installer now detects the
  Microsoft Visual C++ Runtime required by the official Qdrant Windows binary.
  When it is missing or older than 14.44, Ariadne downloads Microsoft's
  official redistributable, verifies its Authenticode signer, and requests
  administrator approval for that prerequisite only.
- **Actionable Qdrant failures** — startup gets a full 60-second window, loader
  and process errors are preserved in `~/.ariadne/logs/qdrant.log`, and the
  installer prints the scheduled-task result plus the last log lines instead of
  returning only a generic timeout.
- **Real Windows Qdrant coverage** — CI now downloads the exact pinned Qdrant
  archive, verifies its SHA-256 digest, starts it with Ariadne's loopback/storage
  settings, and waits for `/healthz` on a Windows runner.

## What's New in v0.3.0

- **Native Windows installation** — `install.ps1` installs release binaries,
  native Qdrant, signed Ollama, user-level startup tasks, Codex/Claude Code MCP
  bindings, the skill, and session hooks. Docker is not required; administrator
  approval is needed only when Windows lacks Qdrant's Microsoft VC++ Runtime.
- **Windows self-updates** — the version-aware tray now offers the same explicit
  confirmation and automatic restart flow on Windows as on macOS and Linux.
- **Five release targets** — Windows x64, Linux x64/ARM64, and macOS
  Intel/Apple Silicon archives are built from tags by GitHub Actions.
- **Verifiable artifacts** — releases include SHA-256 checksums, a CycloneDX
  SBOM, and a keyless Sigstore bundle for the checksum manifest.
- **MCP discovery** — a cross-platform MCPB and `server.json` are generated from
  the release binaries and published to the official MCP Registry with GitHub
  OIDC.
- **Public project site and launch kit** — structured metadata, `llms.txt`,
  platform installation paths, architecture, security notes, and ready-to-use
  launch copy make Ariadne easier for both people and AI systems to discover.

## Why

- **Stable** — Qdrant server, not an embedded HNSW that SIGSEGVs on compaction.
- **Multilingual** — bge-m3 covers 100+ languages; cross-lingual recall works
  (an English query finds Ukrainian notes, cosine ~0.8–0.94 across uk/ru/en/es/
  de/it/pl/ro/hu/lt/lv/et/fi/fr/ar).
- **Hybrid search** — dense (bge-m3) + BM25 sparse (pure