Vesma

A memory & knowledge server for AI agents
named after the Vesper of memory, built for AI agents that need to remember

🇬🇧 English · 🇷🇺 Русский

Quick start · Features · What it is · Connect a harness · Architecture · Docs

AI agents forget everything when a session ends. Vesma gives them a place to lay it down — structured, searchable, governed by contract — so what they learn does not vanish with the closing of a window.

• Local-first. One process on your machine. SQLite + a bundled embedding model; nothing leaves the host, no API keys, works offline.
• One server, any harness. VS Code Copilot, Claude Code, Cursor, OpenCode, Codex, Windsurf, ZCode, pi, Hermes — the same MCP wire, one line each.
• The agent learns to use it. Not just tools: always-on instructions, a skill pack, and a memory-first prompt mode, deployed into your harness in one command.

🚀 Quick start

Three commands from an empty machine to an agent that remembers — and knows when to look.

1 · Install the server

pip install vesma

One package, everything included: the memory server, the vesma CLI, the REST API, and the MCP server your agent harness talks to. The embedding model ships inside — search works fully offline, no API keys, nothing downloaded.

⚠️ Names. The product and the CLI are vesma (pip install vesma, PyPI slot project/vesma). The pre-rebrand packages remain live until deprecation: pip install mnemos-memory-server installs the same server under the legacy name (its legacy CLI spelling was mnemos, now an alias). The bare pip install mnemos is an unrelated project — do not use it.

Or take the prebuilt image — Docker, Podman, or a Kubernetes cluster

The same server ships as a public image (ghcr.io/vesmaro/vesmaro) — pull and run: no build, no login. Full guides live in the admin docs.

helm install vesmaro deploy/helm/vesmaro \
  --namespace vesmaro --create-namespace \
  --set auth.totpMasterKey="$(openssl rand -hex 32)" \
  --set ingress.className=traefik \
  --set 'ingress.hosts[0].host=vesma.example.com'
kubectl -n vesmaro rollout status deploy/vesmaro

cd deploy/docker
cp .env.example .env                    # put your TOTP_MASTER_KEY=$(openssl rand -hex 32) inside
docker compose up -d                    # podman-compose works too
curl -fsS http://localhost:8787/health  # → {"status":"ok"}

# systemd user service (preferred for a long-running host)
# legacy-named asset — unit file stays mnemos.container until the deploy wave renames it
cp deploy/podman/quadlet/mnemos.container ~/.config/containers/systemd/
# add the TOTP key to ~/.vesmaro.env (both env spellings), then:
podman pull ghcr.io/vesmaro/vesmaro:4.3.0
# quadlet derives the unit name from the file name — the unit is mnemos.service for now
systemctl --user daemon-reload && systemctl --user start mnemos
curl -fsS http://localhost:8787/health

2 · Connect your harness — and teach it to use memory

vesma integration setup

One pass: detects the agent harnesses on your machine, registers the Vesma MCP server in each supported one (VS Code Copilot, Cursor, ZCode, OpenCode, pi, Hermes, and everything reading the ~/.agents standard — Claude Code, Codex and friends), and deploys the behavioral pack — always-on instructions and memory skills, so the agent recalls at session start, checkpoints before its context gets compacted, and treats memory as a priority instead of forgetting the tools exist.

Running a harness that reads nothing standard? One paste block per harness: Connect Vesma to any harness.

3 · Verify — then try it

vesma doctor

PASS / WARN / FAIL per check: store, config, MCP transport, harness registration (--fix repairs the common warnings). Then give it a memory:

vesma add "First memory — Vesma remembers across sessions" \
  --tags project:vesma,agent:me,vesma:learning
vesma search "remembers across sessions"

That is the whole loop: write, find, never lose it — and the agent knows when to look.

📘 Want every detail? The extended guide covers all install variants (uv tool, pipx, CLI-only, external LLM extras, installer script, container), per-harness connection walkthroughs, configuration, and troubleshooting: Getting Started — the complete first run.

✨ Features

One local server — and a connected agent harness gets the full memory stack.

Autonomy for an arbitrary harness and LLM-driven enrichment are partial — the full, honest map lives in docs/en/features.md.

🧩 What Vesma is

A single-tenant, local-first memory server for AI agents. One in-process core, three equivalent control surfaces, and a storage layer you can read with your own eyes.

SQLite for metadata, a local numpy + SQLite vector index for recall, and an Obsidian-compatible vault for the humans in the loop.

Where this is going. The shipped, measured rung is stores and finds. The next rungs — collapse with checks (session → project → cross-project synthesis: automatic by default, but never unconditional in authority — every derivative traces back to its sources, nothing pins without an operator) and, later, builds understanding — open only as pre-registered experiments prove them (ADR-0025). The invariant on that road is zero silent losses: a fact is either retained, or its loss is visible. And the shape of the ambition is a nervous system, not a conductor — memory that surfaces the right thing at the right moment, never one that conducts the agent.

🤝 Connect any harness

Vesma works with every MCP-capable agent harness. Three integration levels — pick the strongest one your harness supports:

• Native targets — vesma integration setup --target <name> deploys the behavioral pack and registers the MCP server in one pass (integration guide).
• One-line presets — integrations/mcp-presets.md: every harness above, copy-paste ready.
• Adapter template — integrations/adapter-template.md: Connect / Expose / Configure + acceptance checklist for any harness that speaks MCP stdio.
• Hermes Agent runs Vesma in-process: pip install vesma in the Hermes environment, then vesma integration setup --target hermes (details).

The shared contract is the tag schema — project:<slug>, agent:<slug>, and at least one mnemos:<subtype> (tag namespace — unchanged wire contract) — that every memory entry must carry.

🏗️ Architecture

flowchart TB
    subgraph CLIENTS["Clients"]
        C1(["Agent harness\nstdio MCP"])
        C2(["CLI — vesma …"])
        C3(["HTTP API client"])
    end

    subgraph IFACE["Interface Layer"]
        MCP["mcp_server.py"]
        FAPI["api/main.py · FastAPI"]
        TYPER["cli/main.py · Typer"]
    end

    MGR(["MemoryManager\nmanager.py"])

    subgraph PROC["Processing Subsystems"]
        CF["Context Filter\nfilter/"]
        PP["Knowledge Pipeline\npipeline/"]
        RE["Recall Engine\nrecall/"]
        PE["Policy Engine\npolicy/"]
    end

    subgraph BG["Background Services"]
        WA["Watchers\nwatchers/"]
        AC["Auto-collect\nauto_collect.py"]
    end

    subgraph STORE["Storage Layer"]
        SQ[("SQLite\nFTS5 · traces · projects")]
        VS[("Vector Store\nnumpy + SQLite")]
        VLT[("Obsidian Vault\nmarkdown mirror")]
    end

    C1 -->|"stdio"| MCP
    C2 --> TYPER
    C3 --> FAPI
    MCP --> MGR
    TYPER --> MGR
    FAPI --> MGR
    MGR --> CF
    MGR --> PP
    MGR --> RE
    MGR --> SQ
    MGR --> VS
    MGR --> VLT
    CF -.->|"raw + clean"| SQ
    PP -->|"status transitions"| SQ
    PP -->|"published upsert"| VS
    RE -->|"FTS5 MATCH"| SQ
    RE -->|"cosine search"| VS
    PE -->|"schedule / trigger"| MGR
    WA -->|"file events"| MGR
    AC -.->|"checkpoint reminder"| MCP

A deeper walkthrough — data model, state machines, security boundaries, operational concerns — lives in architecture/overview.md.

🎛️ Three surfaces, one core

The same MemoryManager powers all three interfaces. Pick the one that fits your client.

The HTTP surface also exposes the A2A Sessions API — a persistent backend for multi-step agent conversations that survive restarts. See a2a-sessions.md.

📚 Documentation

📖 The lore

In Hesiod's Theogony, Mnemosyne (Μνημοσύνη) is the Titaness of memory — she who, by Zeus, gave birth to the nine Muses and through them made the world's remembering possible. Her name is the root of mnemonic, and she is what every singer, poet, and philosopher prays to before they begin.

The lore section below preserves the memory of the pre-rebrand name — the product itself now sails under Vesma, carrying the same task: to make remembering possible for the things that think. AI agents, unmoored from any single conversation, lose everything that came before. Vesma gives them a place to lay it down — structured, searchable, governed by contract — so that what they learn does not vanish with the closing of a session. The Muses, after all, were not for the gods' benefit. They were for the songs.

⚖️ License & contributing

Apache-2.0 — see LICENSE and NOTICE. Source: github.com/vesmaro/vesmaro.

Contributions are welcome — CONTRIBUTING.md has the development setup, the branch and commit conventions, and the quality gate a change must pass.

🛠 CI / Релизы — кластерный конвейер release-pipeline

Этот проект подключён к общему кластерному конвейеру релизов (Korrnals/release-pipeline, K3s abyss-ai-agent, namespace release-pipeline). GitHub Actions не используется (биллинг аккаунта заблокирован) — конвейер и есть штатный путь релизов. Релизный артефакт подписывается трёхслойно: SHA256 → SBOM → cosign → GPG.

Релиз новой версии:

1. VERSION → релизный коммит (конвенция репо) → тег vX.Y.Z → push.
2. Обновить версию проекта в projects[] файла ~/.cache/release-pipeline-values.yaml и применить:

   helm upgrade --install release-pipeline \
     ~/LABs/Projects/Project-Umbra/release-pipeline/chart/release-pipeline \
     --kube-context abyss-ai-agent -n release-pipeline \
     -f ~/.cache/release-pipeline-values.yaml
   

3. Наблюдение: kubectl --context abyss-ai-agent -n release-pipeline get jobs, логи: kubectl ... logs -f job/release-<proj>-<ver>.

Подробности (типы проектов, kaniko-контейнеры, teardown): README конвейера.