Visp Memory docs.

How memory carries forward

Visp Memory stores project knowledge outside the conversation, so a coding agent can retrieve it in a later session.

It complements your agent’s instruction files: those describe how to work; memory supplies relevant history, decisions, warnings, and goals.

Further reading: injection policy and provenance and trust.

Architecture

One memory core, several ways in.

The Python Memory facade coordinates configuration, memory layers, storage, and retrieval. The CLI and MCP server expose that core; an optional FastAPI server lets the dashboard and remote clients use it.

Three kinds of memory

EpisodicWhat happened

Decisions, discoveries, and bug fixes, including the reasoning behind a change.

SemanticWhat is known

Reusable facts, conventions, patterns, and warnings. Immutable evidence is stored apart from semantic beliefs, and a belief can’t be written without evidence from the same project.

IntentWhat comes next

Goals, focus, and constraints that give context to the current task. Outcome records do not make memory the authority for task completion status.

Where your data lives

SQLite is the default storage backend, and keyword search always works. Semantic search needs both an embedding provider and the Chroma vector index, so install them together: visp-memory[chroma,local-embeddings] for sentence-transformers, [chroma,ollama] for Ollama, or [chroma,openai] for OpenAI or OpenRouter. Changing the provider or model needs an index rebuild.

Source references: memory core, architecture reference, and evidence contract. Use the feature status below when evaluating optional backends.

Functionality & support

What is stable today, and what is still settling.

Checked against the upstream feature status for release 0.9.0 on October 11, 2026. Use your installed command’s --help to check release-specific options.

User guide

Four steps, in order. Each one ends with something you can check.

1. Install and initialize

Use Python 3.10 or newer and run these commands from your project’s git repository. A virtual environment keeps the installation separate from system Python. The extras enable MCP and git capture.

python -m venv .venv
# macOS / Linux; Windows PowerShell: .venv\Scripts\Activate.ps1
source .venv/bin/activate
python -m pip install "visp-memory[mcp,capture]"
visp-memory init
visp-memory doctor

Initialization creates visp-memory.yaml and stores data under .visp-memory/data by default, adding the data directory to git ignores. It uses the project name as the default repository scope and seeds from history. Use visp-memory init --no-mine instead if you want an empty store, or run visp-memory demo to try capture and recall in a temporary store first.

docker run -d --name visp-memory \
  -p 127.0.0.1:8000:8000 \
  -v visp-memory-data:/data \
  -e VISP_MEMORY_EMBEDDING_PROVIDER=noop \
  ghcr.io/djkeshawa/visp-memory:0.9.0
docker logs visp-memory

2. Make memory reachable by your agent

visp-memory hooks list
visp-memory hooks install claude-code --mcp   # hooks, plus the MCP server in .mcp.json
visp-memory hooks install codex
visp-memory doctor

For Claude Code, --mcp merges a visp-memory server into the project’s .mcp.json without replacing your other servers. The Codex integration adds project instructions to AGENTS.md and a visp-memory-mcp entry in ~/.codex/config.toml, keeping a backup of the old file. Review the generated files and look for “Agent reachability: reachable” in the doctor output. Other targets include cursor, aider, and generic.

{
  "mcpServers": {
    "visp-memory": {
      "command": "visp-memory-mcp",
      "args": [],
      "cwd": "/absolute/path/to/your-project",
      "env": {
        "VISP_MEMORY_MCP_PROFILE": "core",
        "VISP_MEMORY_EMBEDDING_PROVIDER": "noop",
        "VISP_MEMORY_AGENT": "your-client-name"
      }
    }
  }
}

visp-memory serve --shared                       # once, on your machine
visp-memory connect --agent-config claude-code   # in each project; or codex

3. Record useful knowledge

Write concrete statements with a reason or file context. These examples illustrate a project that uses bounded API retries, one per kind of memory:

visp-memory decision "Limit API retries to three" "Avoid retry storms during outages"
visp-memory warn "src/api/client.py" "Keep retries bounded to avoid retry storms"
visp-memory record "Fixed duplicate requests after client timeouts"
visp-memory goal "Improve API resilience" --priority 2

4. Recall before changing code

Use search to explore what was recorded. Use a task brief when preparing work; its file scope and token budget keep the output focused.

visp-memory recall "API retries"
visp-memory brief "Update API retry handling" --file src/api/client.py --tokens 1200
visp-memory preview "Update API retry handling" --file src/api/client.py
visp-memory audit

A brief reports an active goal only when the task shares a topic word with it; otherwise it lists the goal under unknowns. brief and recall also take --ranking-strategy hybrid or hybrid_union, which are experimental.

After the change, record the new decision or lesson so the next session can use it.

Command reference: CLI source and upstream setup guide.

Where it helps

Resume a feature after a break

Record the current goal and design decisions before stopping. Prepare a brief in the next session to recover the rationale and constraints.

Avoid repeating a bug

Save the root cause and fix as an event, then attach a warning to the fragile area. Retrieve that file’s context before another change.

Revisit an architectural choice

Record what you chose, why, and alternatives with decision --alt. Search that history before proposing a replacement.

Start on an established repository

Mine git history to get initial context, then check the source evidence against the code. Historical commits are clues, not a guarantee that a claim is still current.

Move between coding assistants

Connect each assistant to the same project store through CLI instructions or MCP. Each client still needs its own integration configured.

A new repository has little history to retrieve. Start by writing decisions. Visp Memory is focused on codebase knowledge, and the current evidence does not establish that it improves an agent’s code quality. See the upstream benchmark scope and limitations.

When something is missing

The agent never uses memory

Run doctor, install the appropriate hooks, and review the project instructions. For MCP, restart the client and verify its executable path and working directory.

Search or injection is empty

Check that you are in the initialized project and correct repo scope. Try a specific query with a file path, inspect audit, and use preview for injection decisions. No injected memory can be an intentional result.

A command is refused because a server owns the data directory

While a server runs on a store, local CLI, MCP and hook processes on that directory are refused, with a message naming the server. Switch those projects to client mode with visp-memory connect.

visp-memory[mcp] won’t install next to another tool

Since 0.9.0 the mcp extra uses MCP SDK 2.x, so it conflicts with an environment pinned to mcp<2. Install Visp Memory in its own virtual environment. Clients on older protocol versions still connect.

A command or tool is unavailable

Check visp-memory --help and the subcommand’s --help. MCP requires the mcp extra; API serving requires api. Development-branch documentation may describe options absent from an older release.