# CLI Reference
Complete reference for all vipune commands.
## Global Flags
These flags apply to all commands:
| Flag | Short | Description |
|------|-------|-------------|
| `--json` | | Output as JSON (pretty-printed) instead of human-readable text |
| `--project <id>` | `-p` | Project identifier (auto-detected from git if omitted) |
| `--db-path <path>` | | Override database path |
## Commands
### add
Store a memory.
```
vipune add <text> [--metadata <json>] [--force] [--memory-type <type>] [--status <status>] [--importance <level>] [--supersedes <id>]
```
**Arguments:**
- `text` - Memory text content (required)
**Flags:**
- `-m, --metadata <json>` - Optional JSON metadata (e.g., `{"topic": "auth"}`). Omitting it is legal; a **present** value must be non-blank and parse as JSON — see [Metadata is validated on write](#metadata-is-validated-on-write)
- `--force` - Bypass conflict detection and add regardless
- `--memory-type <type>` - Memory type: `fact` (default), `preference`, `procedure`, `guard`, `observation`
- `--status <status>` - Initial status: `active` (default) or `candidate`
- `--importance <level>` - Initial importance: `low`, `medium` (default), `high`, or `critical` (case-insensitive). `high` and `critical` are a hard exclusion for `prune`, which never demotes such a row
- `--supersedes <id>` - Atomically supersede an existing memory (mutually exclusive with `--force`)
**Behavior:**
- Generates semantic embedding for the text
- Checks for similar existing memories (similarity ≥ threshold)
- If conflicts found: returns exit code 2, lists conflicting memories
- If `--force` used: skips conflict check and adds memory
- If `--supersedes` used: atomically adds new memory and marks target as `superseded`. The target must still be `active` or `candidate`: superseding a row that is already `superseded` (which would fork the chain into a replacement nothing points at) or `deprecated` is refused with `Invalid input: cannot supersede memory <id>: status is already '<status>'` (plus ` (superseded_by <id>)` when set) and writes nothing — `prune` demotions stay final. The guard sits in the storage tier's supersede transaction (`Database::supersede_with_importance`, a `BEGIN IMMEDIATE` body every supersede route funnels through), so the MCP `store_memory` `supersedes` parameter and `supersede_memory` are refused the same way
- `--importance` is stored on the new row (also on the row created by `--supersedes`), and `export` writes that value so `import` restores it
- `--status` is stored on the new row too, including the row created by `--supersedes`. Only `active` and `candidate` are valid here: `--status superseded`/`deprecated` is rejected with or without `--supersedes`, since the old row's `superseded` is set by the supersede transaction itself. A `--status candidate` replacement is hidden from default `search`/`list` (which filter to `status = 'active'`) along with the `superseded` row it replaced — see [Supersede with a candidate replacement](#supersede-with-a-candidate-replacement) for how to read and activate it
**Exit codes:**
- `0` - Successfully added
- `1` - Error (invalid input, database error)
- `2` - Conflicts detected (similar memories exist)
- `3` - Content too long (exceeds embedding token limit)
**Human output:**
```
Added memory: 123e4567-e89b-12d3-a456-426614174000
```
**Conflicts output:**
```
Conflicts detected: 1 similar memory/memories found
Proposed: Authentication uses OAuth2
Use --force to add anyway
123e4567-e89b-12d3-a456-426614174000 (similarity: 0.94)
Auth system uses OAuth2 for login
```
**JSON output (success):**
```json
{
"status": "added",
"id": "123e4567-e89b-12d3-a456-426614174000"
}
```
**JSON output (conflicts):**
```json
{
"status": "conflicts",
"proposed": "Authentication uses OAuth2",
"conflicts": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"content": "Auth system uses OAuth2 for login",
"similarity": 0.94
}
]
}
```
**Supersede example:**
```bash
# Replace an outdated memory atomically
vipune add "Alice now works at Google" --supersedes abc123-old-memory-id
```
This inserts the new memory and marks the old one as `superseded` in a single transaction.
`--status` applies to the row this creates, so a replacement can be staged as a candidate first
(see [Supersede with a candidate replacement](#supersede-with-a-candidate-replacement)):
```bash
vipune add "Alice now works at Google" --supersedes abc123-old-memory-id --status candidate
```
#### Supersede with a candidate replacement
Until it is activated, that replacement is reachable only by id (`vipune get <id>`) or an explicit
candidate filter (`vipune search "alice" --status candidate` / `--include-candidates`) — and the
`superseded` original is hidden too, so neither row shows up in a default `search`/`list`.
Activate it with the id `add` printed:
```bash
vipune update <new-memory-id> --status active
```
`vipune promote` is **not** the way out of this state: it promotes only candidates whose
`retrieval_count` has reached the threshold (default 5), and a supersede does not bump that
counter — only `search`/`get` retrievals do. A candidate that nothing has been retrieved by id
therefore never promotes, which is deliberate (see the `promote` module doc); the explicit
`update --status active` above is the deterministic route.
The same rule is what `store_memory`'s `supersedes` + `status: "candidate"` writes over MCP.
---
### Metadata is validated on write
The rule the `add` and `update` paths share, stated once: a *present* metadata value must be
non-blank and parse as JSON. A blank value is refused with `Invalid input: metadata cannot be
empty`, a non-JSON one with `Invalid input: invalid metadata JSON: <parser message>`; both exit
`1` (only `ContentTooLong` maps to `3`) and write nothing — the check runs before the embedding
call, so a refused row costs no inference. **Omitting** metadata is still legal: the parse is a
gate, never a re-serialisation, and the CLI and library store the accepted document exactly as
passed; over MCP the value arrives already parsed and is re-serialised before the store sees it
(`serde_json::to_string` in `metadata_column`, `src/mcp/helpers.rs`), so
whitespace or key order may differ from what the client sent.
The rule lives in the store's `add`, `supersede` and `update` bodies, so every public
add/supersede/update entry point inherits it — e.g. `MemoryStore::ingest`,
`MemoryStore::ingest_with_type_status`, `MemoryStore::ingest_with_importance`,
`MemoryStore::batch_ingest`, `MemoryStore::supersede`, `MemoryStore::supersede_with` and
`MemoryStore::update`; this is a sample, not a closed list. `batch_ingest` reports the refusal
**per item** (a `BatchIngestItemResult::Error` for that index) and still stores the other items,
rather than failing the batch. There is no `vipune ingest`/`batch_ingest` command: those are
library-only.
The storage tier below the store validates nothing, so `vipune import` is unchanged — a dump is
taken as given — and the hook insert path (`src/hook/run.rs` → `Database::insert_with_hash`)
has nothing to check because it passes no metadata (`None`).
(`update --status` is the route named above, and its own flag table notes the one asymmetry it
has with `add --status`.)
---
### search
Find memories by semantic similarity.
```
vipune search <query> [--limit <n>] [--recency <weight>] [--hybrid] [--memory-type <types>] [--status <statuses>] [--include-candidates]
```
**Arguments:**
- `query` - Search query text (required)
**Flags:**
- `-l, --limit <n>` - Maximum results to return (default: `5`)
- `--recency <weight>` - Recency bias for scoring, 0.0 to 1.0 (default: from config, typically `0.3`)
- `--hybrid` - Enables hybrid search combining semantic similarity with FTS5 full-text search using Reciprocal Rank Fusion (RRF)
- `--no-hybrid` - Disables hybrid search even when enabled in config (useful to force pure semantic search)
- `--memory-type <types>` - Filter by memory type (comma-separated, e.g., `guard,procedure`)
- `--status <statuses>` - Filter by status (comma-separated, e.g., `active,candidate`)
- `--include-candidates` - Shorthand to include both `active` and `candidate` memories
- `--no-touch` - Do not update retrieval telemetry (`retrieval_count`, `last_retrieved_at`) for the returned memories (default: telemetry is updated)
**Behavior:**
- Generates embedding for query
- Unless `--no-touch` is set, increments `retrieval_count` and sets `last_retrieved_at` for every returned memory (see [Retrieval telemetry](#retrieval-telemetry))
- Finds memories with highest cosine similarity
- Combines semantic similarity with time decay for final score
- Returns results sorted by final score (highest first)
- All memories in current project scope
- **Default filtering:** Only `active` memories are returned by default. Use `--status` or `--include-candidates` to include other statuses.
**Recency scoring:**
The final score combines: `(1 - recency_weight) * similarity + recency_weight * time_score`
- `recency_weight = 0.0`: Pure semantic similarity
- `recency_weight = 1.0`: Pure recency (newest first)
- `recency_weight = 0.3`: Default balance (70% semantic, 30% recency)
**Exit codes:**
- `0` - Success (may return empty results if no matches)
**Human output:**
```
123e4567-e89b-12d3-a456-426614174000 [score: 0.95]
Alice works at Microsoft as a senior engineer
234e5678-e89b-12d3-a456-426614174001 [score: 0.87]
Bob is a software engineer at Google
```
**JSON output:**
```json
{
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"content": "Alice works at Microsoft as a senior engineer",
"similarity": 0.95,
"created_at": "2024-01-15T10:30:00Z",
"retrieval_count": 12,
"last_retrieved_at": "2024-01-20T09:15:00Z",
"memory_type": "fact",
"status": "active"
},
{
"id": "234e5678-e89b-12d3-a456-426614174001",
"content": "Bob is a software engineer at Google",
"similarity": 0.87,
"created_at": "2024-01-16T14:20:00Z",
"retrieval_count": 0,
"last_retrieved_at": null,
"memory_type": "fact",
"status": "active"
}
]
}
```
**Recency example:**
```bash
# Default recency balance (0.3)
vipune search "authentication"
# High recency bias (recent memories rank higher)
vipune search "authentication" --recency 0.7
# Pure semantic similarity (no time bias)
vipune search "authentication" --recency 0.0
```
---
### get
Retrieve a memory by ID.
```
vipune get <id> [--no-touch]
```
**Arguments:**
- `id` - Memory ID (required)
**Flags:**
- `--no-touch` - Do not update retrieval telemetry (`retrieval_count`, `last_retrieved_at`) for the retrieved memory (default: telemetry is updated)
**Exit codes:**
- `0` - Memory found
- `1` - Memory not found or error
**Human output:**
```
ID: 123e4567-e89b-12d3-a456-426614174000
Content: Alice works at Microsoft as a senior engineer
Project: git@github.com:user/repo.git
Metadata: {"topic": "team"}
Created: 2024-01-15T10:30:00Z
Updated: 2024-01-15T10:30:00Z
```
**JSON output:**
```json
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"content": "Alice works at Microsoft as a senior engineer",
"project_id": "git@github.com:user/repo.git",
"metadata": "{\"topic\": \"team\"}",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"retrieval_count": 5,
"last_retrieved_at": "2024-01-15T10:30:00Z",
"memory_type": "fact",
"status": "active"
}
```
- `retrieval_count` / `last_retrieved_at` reflect retrieval telemetry (see `--no-touch` under `search`). Note that a `get` without `--no-touch` increments the counter before the JSON is emitted, so the value shown is the post-retrieval count.
---
### list
List all memories in the current project.
```
vipune list [--limit <n>] [--memory-type <types>] [--status <statuses>] [--include-candidates]
```
**Flags:**
- `-l, --limit <n>` - Maximum results to return (default: `10`)
- `--memory-type <types>` - Filter by memory type (comma-separated, e.g., `guard,procedure`)
- `--status <statuses>` - Filter by status (comma-separated, e.g., `active,candidate`)
- `--include-candidates` - Shorthand to include both `active` and `candidate` memories
**Behavior:**
- Returns memories ordered by creation time (newest first)
- Limited to current project scope
- **Default filtering:** Only `active` memories are returned by default. Use `--status` or `--include-candidates` to include other statuses.
- Listing does not update retrieval telemetry — `retrieval_count` and `last_retrieved_at` are touched only by `search` and `get` (and the equivalent MCP tools). The `list` command has no `--no-touch` flag because there is nothing to suppress.
**Exit codes:**
- `0` - Success (may return empty list)
**Human output:**
```
123e4567-e89b-12d3-a456-426614174000: Alice works at Microsoft
234e5678-e89b-12d3-a456-426614174001: Bob is a software engineer at Google
```
**JSON output:**
```json
{
"memories": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"content": "Alice works at Microsoft",
"created_at": "2024-01-15T10:30:00Z",
"retrieval_count": 3,
"last_retrieved_at": "2024-01-17T08:45:00Z",
"memory_type": "fact",
"status": "active"
},
{
"id": "234e5678-e89b-12d3-a456-426614174001",
"content": "Bob is a software engineer at Google",
"created_at": "2024-01-16T14:20:00Z",
"retrieval_count": 0,
"last_retrieved_at": null,
"memory_type": "preference",
"status": "active"
}
]
}
```
---
### delete
Delete a memory by ID.
```
vipune delete <id>
```
**Arguments:**
- `id` - Memory ID (required)
**Exit codes:**
- `0` - Memory deleted
- `1` - Memory not found or error
**Human output:**
```
Deleted memory: 123e4567-e89b-12d3-a456-426614174000
```
**JSON output:**
```json
{
"status": "deleted",
"id": "123e4567-e89b-12d3-a456-426614174000"
}
```
---
### update
Update a memory's content.
```
vipune update <id> [text] [--metadata <json>]
```
**Arguments:**
- `id` - Memory ID (required)
- `text` - New content (optional — if omitted, only metadata is updated)
**Flags:**
- `-m, --metadata <json>` - Replace metadata (must be valid JSON)
- `--status <status>` - Set lifecycle status (`active`, `candidate`, `deprecated`, `superseded`); `superseded` is rejected with an error — that status is written only by `add --supersedes`. Unlike `add --status`, which accepts only `active`/`candidate` (see [Supersede with a candidate replacement](#supersede-with-a-candidate-replacement) for why an insert may not name the other two), this path does accept `deprecated`, which is what `prune` writes
**Behavior:**
- If only `text` provided: generates new embedding, preserves metadata
- If only `--metadata` provided: updates metadata without re-embedding
- If both `text` and `--metadata` provided: updates both
- Metadata must be valid JSON when present (validated on write — see [Metadata is validated on write](#metadata-is-validated-on-write))
**Exit codes:**
- `0` - Memory updated
- `1` - Memory not found or error
**Human output:**
```
Updated memory: 123e4567-e89b-12d3-a456-426614174000
```
**JSON output:**
```json
{
"status": "updated",
"id": "123e4567-e89b-12d3-a456-426614174000"
}
```
---
### validate
Check if text content is within the embedding model's token limit.
```
vipune validate <text>
```
**Arguments:**
- `text` - Text to validate (required)
**Exit codes:**
- `0` - Within token limit
- `3` - Content exceeds token limit
**Human output:**
```
Token count: 42/512 — within limit
```
**JSON output:**
```json
{
"token_count": 42,
"max_tokens": 512,
"within_limit": true
}
```
---
### version
Display version information.
```
vipune version
```
**Exit codes:**
- `0` - Success
**Human output:**
```
vipune 0.1.1
```
**JSON output:**
```json
{
"version": "0.1.1",
"name": "vipune"
}
```
*Note: Output version matches your installed version. Update this example when upgrading vipune.*
---
### mcp
Start vipune as an MCP (Model Context Protocol) server over stdio. This enables AI agents like Claude Code and Cursor to use vipune as a native memory provider.
```
vipune mcp
```
**Behavior:**
- Starts MCP server on stdin/stdout
- Exposes three tools: `store_memory`, `search_memories`, `list_memories`
- Automatically detects project from git repository
- Uses default database path (`~/.vipune/memories.db`)
**Available Tools:**
| Tool | Description |
|------|-------------|
| `store_memory` | Store information for later recall |
| `search_memories` | Find memories by meaning, with type/status filters |
| `list_memories` | List recent memories, with type/status filters |
| `supersede_memory` | Replace an existing memory with new content |
| `get_memory` | Retrieve a specific memory by ID |
| `delete_memory` | Delete a memory permanently by ID |
| `update_memory` | Update an existing memory's content, metadata, type, status, or importance |
**Exit codes:**
- `0` - Success
- `1` - Error (initialization failed)
**New v0.3 tool parameters:**
`store_memory` accepts:
- `text` — the information to remember (required)
- `metadata` — optional structured labels as a JSON document (e.g., `{"topic": "auth"}`). Omitting it is legal. The CLI/library wording of the rule is [Metadata is validated on write](#metadata-is-validated-on-write); over MCP the argument is a parsed JSON value, so the usual refusal is `Invalid metadata: <serializer message>`; a JSON *string* value, though, survives the round-trip and reaches the store's own check, so `" "` or `"{bad"` is refused there with the wording above
- `memory_type` — type of memory: `fact` (default), `preference`, `procedure`, `guard`, `observation`
- `status` — initial status: `active` (default) or `candidate`. Stored on the new row, including the row created by `supersedes` (see [Supersede with a candidate replacement](#supersede-with-a-candidate-replacement) for what a hidden `candidate` replacement means and how to activate it)
- `importance` — initial importance: `low`, `medium` (default), `high`, or `critical` (case-insensitive; the tool schema advertises the four canonical spellings as an `enum`, and the handler accepts any casing). `high` and `critical` are a hard exclusion for `prune`, which never demotes such a row. The level also affects search ranking: `critical` never recency-decays and `high` decays slowly, so they keep their recency score longer than `medium` and `low`. Stored on the new row, including the row created by `supersedes`. Importance can be changed later with `update_memory`. `supersedes` and `force` are mutually exclusive, as on the CLI: sending both is rejected with no row written
- `supersedes` — ID of memory to supersede (atomically replaces old memory; mutually exclusive with `force`). The target must still be `active` or `candidate` — superseding a row that is already `superseded` or `deprecated` is refused as `invalid_input` and writes nothing, exactly as on the CLI (see the `--supersedes` bullet under [`add`](#add), the single statement of that guard)
- `force` — force store even if conflicts detected (default: `false`)
`supersede_memory` accepts:
- `new_text` — the new content that replaces the old memory (required)
- `old_memory_id` — ID of the memory to supersede (required)
- `memory_type` — optional type for the new memory (default: `fact`)
- `metadata` — optional structured labels as a JSON document; omitting it — or sending it as JSON `null` — stores **no** metadata (SQL NULL), the same as `store_memory` (see the `store_memory` `metadata` bullet above). Rows written by this tool before the fix may still hold the literal string `null` in the column; reads render that as JSON `null` too and no migration rewrites them
It has no `status` parameter, so the row it creates is always `active`. Stage a `candidate` replacement through `store_memory` with `supersedes` + `status` instead.
`get_memory` accepts:
- `id` — ID of the memory to retrieve (required)
- `no_touch` — skip updating retrieval telemetry (default: `false`)
`delete_memory` accepts:
- `id` — ID of the memory to delete (required)
`update_memory` accepts:
- `id` — ID of the memory to update (required)
- `text` — optional new content for the memory
- `metadata` — optional new metadata as a JSON document. **Unlike `store_memory` and `supersede_memory`**, which store SQL NULL for an omitted or JSON-`null` argument, here omitting it — or sending it as JSON `null` — leaves the stored metadata **unchanged** (see the `store_memory`/`supersede_memory` `metadata` bullets above). There is consequently no MCP way to clear a row's metadata: send a document to replace it, or delete and re-store the row
- `memory_type` — optional new memory type
- `status` — optional new status: `active` or `candidate`
- `importance` — new importance: `low`, `medium`, `high`, or `critical` (case-insensitive; the tool schema advertises the four canonical spellings as an `enum`, and the handler accepts any casing). Omitting it leaves the row's level unchanged; an invalid value is rejected before any write. This is the only MCP demotion path: `prune` never demotes `high`/`critical`, so an over-rated row stays prune-exempt until it is demoted here
(At least one optional field must be provided)
`search_memories` and `list_memories` accept optional:
- `memory_types` — array of types to filter by (e.g., `["guard", "procedure"]`)
- `statuses` — array of statuses to filter by (e.g., `["active", "candidate"]`)
- `no_touch` — skip updating retrieval telemetry (default: `false`)
`search_memories` also accepts:
- `recency_weight` — recency bias for scoring, 0.0 to 1.0 (default: config value)
- `hybrid` — use hybrid search (semantic + BM25), true/false (default: config value)
**Example MCP configuration (Claude Code):**
```json
{
"mcpServers": {
"vipune": {
"command": "vipune",
"args": ["mcp"]
}
}
}
```
---
## Upgrading from v0.2
v0.3 includes automatic schema migrations — no manual steps required. On first run after upgrading, vipune will add the new `type`, `status`, and `superseded_by` columns to your existing database. All existing memories default to type `fact` and status `active`.
**Breaking change:** Content that previously was silently truncated when exceeding the embedding token limit now fails with exit code 3. Use `vipune validate <text>` to check content length before adding.
## Retrieval telemetry
`search` and `get` maintain two telemetry columns per memory: `retrieval_count` (how many times the memory has been returned by `search` or `get`) and `last_retrieved_at` (timestamp of the most recent retrieval). Both commands accept `--no-touch` to skip updating them — useful for reads that should not influence ranking or promotion signals.
`search` and `get` include `retrieval_count` and `last_retrieved_at` in their JSON output (`--json`). Retrieval via `list` does not count as a retrieval and never touches telemetry.
---
## Exit Codes Summary
| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Error (invalid input, database error, not found) |
| `2` | Conflicts detected (similar memories exist) |
| `3` | Content too long (exceeds embedding token limit) |
| `64` | Usage error (invalid flag or argument — clap argument-parsing failure) |
*Note: Argument-parsing errors exit `64` (`EX_USAGE` from the sysexits convention), so exit code `2` unambiguously means "conflicts detected". Previously, usage errors also exited `2`, which collided with the conflict code — integrations that branched on exit code alone could not distinguish a semantic conflict from a typo'd flag.*
---
## Project Detection
vipune automatically detects projects from git repositories. When inside a git repo, the project ID is inferred from the remote origin URL.
**To override project scope:**
```bash
vipune add "Memory for specific project" --project "my-custom-project"
```
**Project ID examples:**
- Inside `~/projects/myapp/.git`: `git@github.com:user/myapp.git`
- No git repository: `default` (all memories share default scope)
---
## Migrating nested-namespace projects
Repositories with a **nested namespace** in their remote URL can resolve to different `project_id`s depending on the URL form, silently fragmenting recall. This affects GitLab **subgroups**, Gitea **organisations**, self-hosted **Forgejo**, and **Azure DevOps** — any host where the path has more than two segments. Plain `github.com/owner/repo` (two segments) is unaffected because both URL forms agree.
**How the split happens:** vipune derives the `project_id` from the `origin` remote. Before the canonicalisation fix (see [#164](https://github.com/randomm/vipune/issues/164)), the two URL forms used **different** truncation rules for nested paths:
| Remote URL | Old project_id |
|---|---|
| `https://gitlab.example.com/group/subgroup/project.git` | `subgroup/project` |
| `git@gitlab.example.com:group/subgroup/project.git` | `group/subgroup/project` |
If you switched the remote between HTTPS and SSH — or cloned one way on one machine and the other way elsewhere — the same repository's memories got filed under two different ids. A search scoped to one cannot see the other, and nothing signals it.
**Canonical rule going forward:** for both URL forms, vipune takes the **last two path segments** (`subgroup/project`). The SSH-shortcut and `://` forms now agree, so switching remotes no longer forks your memories. Note this is a **breaking change to existing ids** for affected users — the id for a repo that previously resolved via its remote will change (see the project [CHANGELOG](../CHANGELOG.md)).
**Migration:** repair existing splits. The detect-and-repair tooling from [#158](https://github.com/randomm/vipune/issues/158) Phase 2 makes this safe rather than a silent re-fork.
1. **Detect suspected splits.** `doctor --projects` scans *all* project ids in the database (it ignores `-p/--project`, because a split spans two ids by definition) and reports pairs where one bare id equals a segment of another, with row counts for each side:
```bash
vipune doctor --projects
```
```
Suspected project splits:
'pi-an' (8 rows) + 'randomm/pi-an' (2 rows)
These are suspected pairs — confirm they represent the same repository before merging.
```
Pairs are **suspected only** — they require human confirmation before merging. Known false positives include a genuinely separate project whose directory name matches another project's repo name (`ci-runner` vs `team/ci-runner`).
2. **Merge confirmed pairs.** Move all rows from one id to the other, in a single transaction:
```bash
vipune project merge <from> <to>
```
```
vipune project merge group/subgroup/project subgroup/project
```
```
Merged 12 row(s) from 'group/subgroup/project' to 'subgroup/project'
Note: If a vipune MCP server is running, it holds its project_id from startup. Restart the MCP server to see rows under the new project id.
```
The merge is **user-invoked, never automatic** — it moves rows from `from` into `to` (merging into a target that already holds rows is the normal case), preserves content, timestamps, counters, and embeddings byte-identically, and is idempotent (a second run moves zero rows).
3. **Restart your MCP server** if one is running. It resolves `project_id` once at startup and stays scoped to the old id until restarted, so it will not see the merged rows otherwise.
---
## Error Handling
All commands return exit code `1` on error, with error message to stderr or JSON error response.
**JSON error format:**
```json
{
"error": "Memory not found"
}
```
The `error` key, the output stream, and the exit codes above are stable; only
the message body reflects the underlying failure. Database errors now render
the underlying SQLite message (`Database error: no such table: memories`)
instead of the bare `Database error`.
**What a database error discloses, and where it goes.** The rendered message
is the same string on every surface: the human path writes it to stderr
(`Error: …`), `--json` puts it in the `error` key on **stdout**, and the MCP
server returns it verbatim in its `ErrorData` message. So raw SQLite wording
(`no such table: …`, `UNIQUE constraint failed: memories.id`) is part of the
*data* stream a JSON caller or log shipper consumes — not only a diagnostic
channel — and it is deliberately not filtered: the SQLite message is what makes
a permissions, disk-full, or schema failure actionable. The one exception is a
payload vipune sanitises before it reaches the boundary at all (memory ids in
not-found errors), which is sanitised on every surface alike.
**Common errors:**
- Memory not found (`get`, `update`, `delete`)
- Invalid metadata (not valid JSON) — see [Metadata is validated on write](#metadata-is-validated-on-write)
- Database errors (permissions, disk full)
- Missing or invalid configuration
**Locked database:** when another process (usually a running MCP server) holds
a write lock, commands report the actionable "Database is locked … Stop the
MCP server and retry." message and exit `1` — the same text and the same
classification on every command, since all eight (backup, doctor, doctor --fts,
export, merge, prune, promote, reindex) open the store through one shared
helper. How fast that arrives depends on
where the lock is hit: statements issued after the command has its handle
(the writes, the FTS rebuild) fail immediately, because those handlers set a
zero busy timeout; the **open** itself — which runs schema creation, migrations,
and, when one is pending, a `BEGIN EXCLUSIVE` — happens before that timeout is
applied, so a contended open waits SQLite's default busy timeout (5s) and then
fails. The same 5s applies to a read-only diagnostic open and to its first
statement: taking even a shared read lock contends with an exclusive writer, so
nothing in the CLI is lock-free — only calls on a handle whose timeout was
already zeroed fast-fail. The wording itself is not a contract — library consumers match
`vipune::Error::DatabaseLocked` or call `Error::is_locked()` instead: the CLI
renders a lock as a `Config` line for the operator, but it classifies that line
from the typed variant on every entry point alike, so `is_locked()` reads the
same way no matter which command hit the lock.
---
## Examples
**Semantic search:**
```bash
vipune search "how do we handle authentication"
```
**Hybrid search (keywords):**
```bash
vipune search "JWT tokens" --hybrid
```
*See [Search Guide](search.md) for when to use hybrid vs semantic search and how recency weighting works.*
**Find by metadata (via search):**
```bash
# High recency bias for time-sensitive queries
vipune search "recent changes" --recency 0.8
# Pure semantic search for knowledge retrieval
vipune search "authentication architecture" --recency 0.0
```
**Force add despite conflicts:**
```bash
vipune add "Duplicate memory" --force
```
**Batch import (loop in shell):**
```bash
for fact in facts.txt; do
vipune add "$fact" || break
done
```
**Export all memories:**
```bash
vipune list --limit 9999 --json > memories.json
```
**Find and update:**
```bash
# Search for memory
vipune search "auth implementation"
# Get output ID, then update
vipune update 123e4567-e89b-12d3-a456-426614174000 "Auth uses JWT with refresh tokens"
```
**JSON processing with jq:**
```bash
# Add and extract ID
ID=$(vipune add --json "Important fact" | jq -r '.id')
echo "Added: $ID"
# Search and get highest similarity
vipune search --json "test" | jq '.results[0].similarity'
# Check for conflicts in script
if vipune add --json "New fact" | jq -e '.conflicts' > /dev/null; then
echo "Conflict detected!"
fi
```
**Project-specific operations:**
```bash
# Add memory to specific project
vipune --project "my-company/project" add "Company-specific knowledge"
# Search within project
vipune --project "my-company/project" search "API keys"
```
**See also:**
- [Search Guide](search.md) — When to use hybrid vs semantic search, recency weighting
- [Query Guide](vipune-query-guide.md) — Writing effective semantic queries