Visp Memory
documentation.

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.

1. Capture. Initialization mines existing git history and instruction files. You or your connected agent can also record a decision, a bug fix, or a warning explicitly.
2. Store with context. Memories retain their origin and project scope in a persistent local store. Events, reusable knowledge, and intentions have distinct roles.
3. Retrieve for the task. Search finds candidates. A task brief combines relevant memory with evidence citations, constraints, and explicit unknowns within a token budget.
4. Curate what gets injected. Automatic injection applies relevance, trust, duplication, and budget checks. It can return nothing when the evidence is weak. Search results and automatic injection are different surfaces.
5. Record the outcome. Save the reasoning and discoveries worth reusing after work. New projects gain useful history only as someone records it.

Further reading: injection policy and provenance and trust.

Architecture

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.

Episodic: what happened

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

Semantic: what is known

Reusable facts, conventions, patterns, and warnings. Schema v3 separates immutable evidence from semantic beliefs, keeping claims connected to their support.

Intent: what 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.

SQLite is the default storage backend. Keyword search works without an embedding provider; semantic search can use a configured provider such as Ollama, OpenAI, OpenRouter, or optional local sentence-transformers. ChromaDB is an optional persistent vector index.

Local storage does not mean every configuration is offline. Hosted embedding providers send text to the selected service. For an explicit keyword-only setup, set VISP_MEMORY_EMBEDDING_PROVIDER=noop.

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

Functionality & support

Checked against the upstream feature status on September 8, 2026. These docs follow the development branch; use your installed command’s --help to check release-specific options.

User guide

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 --type code
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.

2. Make memory reachable by your agent

Initialization alone does not connect an agent. Install the integration for the tool you use, then check reachability. For example:

visp-memory hooks list
visp-memory hooks install codex
visp-memory doctor

The Codex integration adds project instructions to AGENTS.md. Review the generated instructions and look for “Agent reachability: reachable” in the doctor output. Other supported targets include claude-code, 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"
      }
    }
  }
}

3. Record useful knowledge

Write concrete statements with a reason or file context. These examples illustrate a project that uses bounded API retries:

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

brief produces cited task context. preview explains the automatic injection policy’s selection or abstention; it is not a preview of the separate task-brief compiler. audit helps inspect provenance and injection eligibility. 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 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.