> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MEMO CLI guide

> Write memories, run hybrid search, traverse a four-view relation graph, and batch queries with the local-first MEMO CLI.

MEMO is a local-first long-term memory CLI: pure Rust, SQLite storage, and a local hashing / TF-IDF embedder. It has no runtime network dependency, server, provider key, or cloud account.

## Install and self-management

Download the binary for your platform from [Releases](https://github.com/ariacompute/memo/releases), or self-upgrade an existing binary:

```bash theme={null}
aria-memo upgrade                # upgrade to the latest stable release
aria-memo upgrade 0.5.0          # pin a version
aria-memo upgrade --url <URL>    # override the download URL for this run
aria-memo --version              # print the build version (-v also works)
```

`aria-memo setup` persists the upgrade source to `~/.ariacompute/memo-cli.yml`. Interactive runs let you choose **GitHub** or **Gitee**; non-interactive runs resolve `ARIA_MEMO_SITE=cn` → existing config → the built-in GitHub default. Use `aria-memo setup --status` to inspect the config and `--clear` to delete it.

Release assets follow `aria-memo_{version}_{os}.tar.gz`, where `os` is `linux_x86_64`, `linux_arm64`, `macos`, or `windows_x86_64` (`.zip` on Windows). Override the home directory `~/.ariacompute` with `ARIA_COMPUTE_HOME`.

* Resolution order: `--url` > `~/.ariacompute/memo-cli.yml` > `ARIA_MEMO_UPGRADE_URL` > built-in default.
* Exit codes: `0` success, `1` runtime error, `2` usage error.

## Command reference

Every command accepts the global `--db <path>` flag (default `./memo.db`).

| Command | Key flags | Purpose |
| - | - | - |
| `add` | `--type` `--content` `--importance` (0.5) | Write a memory |
| `get` | `--id` | Read one memory |
| `search` | `--text` `--top-k` (5) `--json` `--graph` | Hybrid search, optionally graph-aware |
| `recall` | `--text` `--top-k` (5) `--json` | Pure-vector recall |
| `search-batch` | `--text` (repeatable) `--top-k` `--json` | Batch hybrid search under one lock |
| `list` | `--type` `--json` | List memories |
| `update` | `--id` `--content` `--type` `--importance` | Update (at least one field) |
| `forget` | `--id` | Forget a memory |
| `bench` | `--size` `--batch` `--json` | Throughput benchmark |
| `connect` | `--id` | Infer four-view edges for a stored memory |
| `relate` | `--from` `--to` `--kind` `--score` | Add a relation edge manually |
| `relations` | `--from` `--to` `--kind` `--json` | List relation edges |
| `graph` | `--text` `--views` `--budget` `--max-hops` `--top-k` `--json` | Bounded multi-relational traversal |
| `setup` / `upgrade` | see above | Configure and self-upgrade |

An unknown `--type` is rejected rather than silently downgraded.

## Memory tiers

`--type` accepts `working`, `short_term`, and `long_term:episodic|semantic|entity|graph`. Tiers have different half-lives: about 1 hour for working, 7 days for short\_term, and 30 days for long\_term. `--importance` participates in decay.

## Retrieval semantics

Hybrid search scores results as `score = 0.7 × cosine + 0.5 × lexical_relevance`.

* **Lexical pushdown**: the SQLite FTS5 table `memories_fts` runs `MATCH` + `bm25()` to prune lexical candidates before cosine scoring. Pure-vector queries, or queries with no lexical hit, fall back to a full scan so semantic recall is preserved.
* **Multilingual segmentation**: Chinese (zh / zh-TW) uses `jieba-rs`, Japanese and Korean use `lindera` (ipadic / ko-dic), and the remaining space-delimited languages use whitespace — covering all 13 playground locales.
* **`recall` is pure cosine**: no keyword component, useful for comparing the semantic signal alone.
* **Batch retrieval**: `search-batch --text "Rust" --text "SQLite" --json` runs every query in one call, sharing one FTS5 preparation and one scan. The JSON result is `[{"query": "...", "results": [{"id", "score", "content"}]}]`. The library also exposes `recall_batch`, but the CLI has no matching subcommand yet.

## Four-view relation plane

Relations are directed edges in a separate `relations` table; `Memo` is never mutated.

| View | Meaning |
| - | - |
| `semantic` | Meaning association (embedding cosine) |
| `temporal` | Ordering / co-occurrence |
| `causal` | Causal chain |
| `entity` | Same-entity aggregation |

```bash theme={null}
# Infer four-view edges for an already-stored memory
aria-memo connect --id <id>

# Add an edge manually
aria-memo relate --from <id> --to <id> --kind semantic --score 0.8

# List edges (filter by from / to / kind)
aria-memo relations --kind semantic --json

# Bounded traversal (views / budget / max hops / top-k)
aria-memo graph --text "Rust systems" --views semantic,entity --top-k 20 --json

# Turn graph awareness on for a plain search
aria-memo search --text "Rust" --graph
```

`search --graph` and `graph` return `items` plus a `trace`. The trace fields are `views`, `budget`, `stop_reason` (`budget` / `exhausted` / `no-seeds`), and `hits`, so the Retrieve→Assess→Expand process stays inspectable. The default `LocalRelationScorer` is fully offline; you can swap in an LLM-backed scorer without touching the controller.

## JSON output

`--json` works with `get`, `list`, `search`, `recall`, `search-batch`, `relations`, `graph`, and `bench`. Without it, search and recall print human-readable `score\tcontent` lines.

## Next steps

* Try adding, searching, batching, and exploring graphs in the [Playground](https://docs.ariacompute.com/guides/playground.md).
* Read the [MEMO memory overview](https://docs.ariacompute.com/concepts/memo-memory.md) and the cloud [AriaMem API](https://docs.ariacompute.com/api-reference/memo/introduction.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.