Skip to content
Back to search

simple-memory

Simple Memory: a local SQLite and FTS5 memory store, prompt hook, and MCP server for coding agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tuanhung303--simple-memory/badge.svg)](/listings/tuanhung303--simple-memory)

HTML

<a href="/listings/tuanhung303--simple-memory"><img src="/api/listings/tuanhung303--simple-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install globally via npm (Node.js 18+) and initialize `~/.simple-memory/`:

npm install -g simple-memory
sm init

You can also run one-off commands without a global install:

npx simple-memory --help

Prebuilt native Rust binaries ship through npm optional dependencies for macOS (`arm64` via `simple-memory-darwin-arm64`, `x64` via `simple-memory-darwin-x64`). On Linux (`x64` and `arm64`), `postinstall` falls back to GitHub Release tarballs when published; otherwise install from source with `./scripts/install.sh` below.

Install globally with `npm install -g simple-memory` (not `npx`) before running `sm hooks print`, so hook and MCP configs point to a stable path. Make sure `node` is on the `PATH` seen by your hook and MCP hosts, or install the standalone native binary via `./scripts/install.sh` for minimal-`PATH` GUI hosts.

Upgrading

Check for a newer release or upgrade with `sm update`:

sm update --check   # check npm for a newer version and refresh the local cache
sm update           # run npm install -g simple-memory@latest for npm installs, or print the source-upgrade command

The first command after an update that opens the store (`sm stats` does) moves `memory.db` to the new schema (version 3 now); the released 0.6.0 still reads and writes it. Copy `memory.db` first if you want the old file. The first catch-up can also store a new version of an imported file in two cases: an older build stored it with a secret in clear, or it is a task log with a one-key list line such as `- pool: 16`, which 0.6.0 stored as `{'pool': 16}` and this build stores as `pool: 16`. `inserted` counts each one; the old version stays as a superseded item (a secret included), and the next catch-up stores nothing.

Interactive npm CLI runs also read `$SIMPLE_MEMORY_HOME/update-check.json` (refreshed in the background at most once every 24 hours) and print a one-line notice to stderr when a newer release exists. The reminder stays silent on non-TTY streams, CI, `mcp`, `hook`/`hooks`, `update`, `--format json`, `--version`/`-v`, `--help`/`-h`, or when `SM_NO_UPDATE_CHECK=1` is set.

Build from source (Linux or custom Rust build)

Requires [Rust (`rustup`)](https://rustup.rs/). `rust/rust-toolchain.toml` pins Rust `1.99.1`. Clone your repository copy and run:

git clone <repo-url>
cd simple-memory
./scripts/install.sh
export PATH="$HOME/.local/bin:$PATH"   # add to your shell profile if needed
sm init

`./scripts/install.sh` builds the release binary from `rust/`, atomically installs `sm` (plus a `simple-memory` symlink) to `SM_INSTALL_DIR` (default `~/.local/bin`), honors `CARGO_TARGET_DIR`, and verifies `sm --version`.

<details> <summary>Manual install and atomic replacement</summary>

Build and replace via a temporary sibling path + `mv -f` rather than overwriting a running binary in place or running `ln -sf`:

cd rust && cargo build --release --locked
mkdir -p ~/.local/bin
cp target/release/sm ~/.local/bin/sm.new && mv -f ~/.local/bin/sm.new ~/.local/bin/sm
ln -s sm ~/.local/bin/simple-memory.new && mv -f ~/.local/bin/simple-memory.new ~/.local/bin/simple-memory

`ln -sf` unlinks the old symlink before relinking (leaving a brief window where a firing hook finds no `sm`), and copying over a mapped binary in place on macOS can break its code signature.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 351 lines
  1. # simple-memory (`sm`)
  2. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  3. [![Rust 1.99.1](https://img.shields.io/badge/rust-1.99.1-orange.svg)](rust/rust-toolchain.toml)
  4. [![SQLite + FTS5](https://img.shields.io/badge/SQLite-FTS5%20bundled-003B57.svg)](DESIGN.md)
  5. [![MCP Ready](https://img.shields.io/badge/MCP-stdio%202026--07--28-10a37f.svg)](#mcp-server-sm-mcp)
  6. A single-binary SQLite + FTS5 memory store, prompt hook, and MCP server for coding agents.
  7. Store verified facts and architectural decisions from the shell with no embeddings or background daemons. Inject matching context automatically via prompt hooks in Claude Code and `agy` (Antigravity CLI), or query and write on demand from any MCP client.
  8. ![How Simple Memory works](assets/flow.svg)
  9. ## Why simple-memory
  10. - **One local SQLite file**: No external database, daemon, or embedding service; everything stays in `~/.simple-memory/memory.db` (WAL mode, bundled SQLite).
  11. - **Evidence-tagged records**: Items store an evidence tag, kind, local timestamp, and extracted references (tickets, commits, paths).
  12. - **Signal-first default ranking**: Exact references rank first, then exact phrases, accented matches, and weighted BM25 biased toward durable verified/decided records.
  13. - **Dual folded and raw FTS5 search**: Folds accents (`dorde` finds `Đorđe`, `cafe` finds `café`) while scoring exact accents higher and prefix-matching 4+ letter ASCII words.
  14. - **Automatic catch-up without cron**: The prompt hook triggers one background pass at most every 10 minutes to rotate checked backups (every 24 h, keep 7), import task logs/handoffs/memory files, and summarize idle sessions.
  15. ## Install
  16. Install globally via npm (Node.js 18+) and initialize `~/.simple-memory/`:
  17. ```sh
  18. npm install -g simple-memory
  19. sm init
  20. ```
  21. You can also run one-off commands without a global install:
  22. ```sh
  23. npx simple-memory --help
  24. ```
  25. Prebuilt native Rust binaries ship through npm optional dependencies for macOS (`arm64` via `simple-memory-darwin-arm64`, `x64` via `simple-memory-darwin-x64`). On Linux (`x64` and `arm64`), `postinstall` falls back to GitHub Release tarballs when published; otherwise install from source with `./scripts/install.sh` below.
  26. Install globally with `npm install -g simple-memory` (not `npx`) before running `sm hooks print`, so hook and MCP configs point to a stable path. Make sure `node` is on the `PATH` seen by your hook and MCP hosts, or install the standalone native binary via `./scripts/install.sh` for minimal-`PATH` GUI hosts.
  27. ### Upgrading
  28. Check for a newer release or upgrade with `sm update`:
  29. ```sh
  30. sm update --check # check npm for a newer version and refresh the local cache
  31. sm update # run npm install -g simple-memory@latest for npm installs, or print the source-upgrade command
  32. ```
  33. The first command after an update that opens the store (`sm stats` does) moves `memory.db` to the new schema (version 3 now); the released 0.6.0 still reads and writes it. Copy `memory.db` first if you want the old file. The first catch-up can also store a new version of an imported file in two cases: an older build stored it with a secret in clear, or it is a task log with a one-key list line such as `- pool: 16`, which 0.6.0 stored as `{'pool': 16}` and this build stores as `pool: 16`. `inserted` counts each one; the old version stays as a superseded item (a secret included), and the next catch-up stores nothing.
  34. Interactive npm CLI runs also read `$SIMPLE_MEMORY_HOME/update-check.json` (refreshed in the background at most once every 24 hours) and print a one-line notice to stderr when a newer release exists. The reminder stays silent on non-TTY streams, CI, `mcp`, `hook`/`hooks`, `update`, `--format json`, `--version`/`-v`, `--help`/`-h`, or when `SM_NO_UPDATE_CHECK=1` is set.
  35. ### Build from source (Linux or custom Rust build)
  36. Requires [Rust (`rustup`)](https://rustup.rs/). `rust/rust-toolchain.toml` pins Rust `1.99.1`. Clone your repository copy and run:
  37. ```sh
  38. git clone <repo-url>
  39. cd simple-memory
  40. ./scripts/install.sh
  41. export PATH="$HOME/.local/bin:$PATH" # add to your shell profile if needed
  42. sm init
  43. ```
  44. `./scripts/install.sh` builds the release binary from `rust/`, atomically installs `sm` (plus a `simple-memory` symlink) to `SM_INSTALL_DIR` (default `~/.local/bin`), honors `CARGO_TARGET_DIR`, and verifies `sm --version`.
  45. <details>
  46. <summary>Manual install and atomic replacement</summary>
  47. Build and replace via a temporary sibling path + `mv -f` rather than overwriting a running binary in place or running `ln -sf`:
  48. ```sh
  49. cd rust && cargo build --release --locked
  50. mkdir -p ~/.local/bin
  51. cp target/release/sm ~/.local/bin/sm.new && mv -f ~/.local/bin/sm.new ~/.local/bin/sm
  52. ln -s sm ~/.local/bin/simple-memory.new && mv -f ~/.local/bin/simple-memory.new ~/.local/bin/simple-memory
  53. ```
  54. `ln -sf` unlinks the old symlink before relinking (leaving a brief window where a firing hook finds no `sm`), and copying over a mapped binary in place on macOS can break its code signature.
  55. </details>
  56. ## 60-second quickstart
  57. Inside any git repository, `sm` automatically scopes writes and queries to that repository (plus `global` and `unassigned` items):
  58. ```sh
  59. sm put --kind decision --tag decided --evidence "ADR-004" --refs ADR-004 \
  60. "Limit HTTP connection pool to 16 sockets per worker"
  61. # m_01M7R350TK1Z1DKWVWT4NSF8MQ
  62. sm put --kind fact --tag verified --evidence "loadtest 10m run, 0 pool waits" --refs ADR-004 \
  63. "Pool size 16 keeps p99 request latency under 12 ms at peak load"
  64. # m_01M7R350W6QV508RDWBHA9S45W
  65. sm query "connection pool ADR-004"
  66. ```
  67. ```text
  68. [m_01M7R350TK1Z1DKWVWT4NSF8MQ] #1 repo=my-repo kind=decision tag=decided as_of=2026-11-18T19:46:44+00:00 ~26 tok why=ref:ADR-004,terms:4/4,bias:decision,bias:decided,recent refs=ADR-004
  69. Limit HTTP connection pool to 16 sockets per worker
  70. [m_01M7R350W6QV508RDWBHA9S45W] #2 repo=my-repo kind=fact tag=verified as_of=2026-11-18T19:46:44+00:00 ~32 tok why=ref:ADR-004,terms:3/4,bias:fact,bias:verified,recent refs=ADR-004
  71. Pool size 16 keeps p99 request latency under 12 ms at peak load
  72. next: sm show m_01M7R350TK1Z1DKWVWT4NSF8MQ m_01M7R350W6QV508RDWBHA9S45W; sm related m_01M7R350TK1Z1DKWVWT4NSF8MQ
  73. ```
  74. `sm query` (alias `sm search`) also accepts unquoted multi-word terms, `-term` or `-"exact phrase"` exclusions (quote the query or use `--` when starting with `-` or excluding multi-word phrases in a shell), and relative `--since` / `--until` bounds (`30m`, `24h`, `7d`, `2w`):
  75. ```sh
  76. sm search connection pool -staging --since 7d
  77. ```
  78. `sm query` also searches `global` and `unassigned`; `sm list` and `sm export` show the current repo only (`--all` or `--repo R` widens them). `sm query --include-history` lists superseded and retired items after the active ones. Search matches whole words split at spaces and punctuation, so Chinese, Japanese or Korean text with no spaces is one word: search for the whole run, or put spaces between its words when you store it.
  79. Open full body and provenance with `sm show` (or `sm show --format json`), update metadata or text append-only with `sm amend`, retire obsolete items with `sm retire`, or replace outdated facts with `--supersedes` (`sm supersede OLD NEW`):
  80. ```sh
  81. sm show m_01M7R350TK1Z1DKWVWT4NSF8MQ
  82. sm amend m_01M7R350TK1Z1DKWVWT4NSF8MQ --add-refs ADR-009
  83. # m_01M7R3512K8Q9V4X7B2N6M3P1R
  84. sm retire m_01M7R350W6QV508RDWBHA9S45W --reason "replaced by new benchmark"
  85. sm put --kind decision --tag decided --supersedes m_01M7R3512K8Q9V4X7B2N6M3P1R \
  86. --evidence "ADR-009" --refs ADR-009 \
  87. "Raise HTTP connection pool to 24 sockets per worker after read-replica split"
  88. ```
  89. `sm put` refuses writes without `--tag`, and requires `--evidence` for `executed` and `verified` items. Duplicate active bodies in the same repo return the existing item ID. When a new item overlaps active work items (`task`, `handoff`) from the last 24 hours or active durable items (`fact`, `decision`, `learning`) in the same repo, `sm put` prints a warning to stderr.
  90. ## Agent integrations
  91. Print ready-to-merge JSON for each harness (`sm hooks print` writes no files):
  92. | Harness | Command | Merge target |
  93. |---|---|---|
  94. | Claude Code | `sm hooks print claude-code` | Top level of `~/.claude/settings.json`: the fragment already holds the `"hooks"` key; when `hooks` exists, add the `UserPromptSubmit` entry to it and keep the entries it holds |
  95. | Antigravity CLI (`agy`) | `sm hooks print agy` | `~/.gemini/config/hooks.json` |
  96. | Any MCP client | `sm hooks print mcp` | Top level of `.mcp.json` or client MCP config: the fragment already holds the `"mcpServers"` key; when `mcpServers` exists, add the `simple-memory` entry to it |
  97. Example output of `sm hooks print claude-code` (a binary path that holds a space is quoted):
  98. ```json
  99. {
  100. "hooks": {
  101. "UserPromptSubmit": [
  102. {
  103. "hooks": [
  104. {
  105. "type": "command",
  106. "command": "/path/to/.local/bin/sm hook prompt",
  107. "timeout": 15
  108. }
  109. ]
  110. }
  111. ]
  112. }
  113. }
  114. ```
  115. ### How the prompt hook works
  116. 1. Skips slash commands, machine-wrapped notifications, and prompts under 3 words.
  117. 2. Uses `claude -p` (Haiku, with hooks, tools, and MCP servers off) to turn the prompt into keywords or `NONE`. For offline IDF local-keyword search with zero model calls, set `model = "none"` under the `[prompt_hook]` header that `sm init` already wrote; a second `[prompt_hook]` header breaks every command.
  118. 3. Falls back to local-keyword search on missing `claude`, error, or timeout (with a 10-minute cooldown after two consecutive failures that clears automatically when `claude_bin`, `model`, or `timeout` changes), skipping built-in English stopwords plus `[prompt_hook] extra_stopwords`.
  119. 4. Injects at most 4 short lines carrying repo, kind, evidence tag, date, compact refs, and title (including `--in <scopes>` in the follow-up hint when project scopes match), and tracks shown IDs per session (per compaction epoch in Claude Code, per `conversationId` in `agy`). When the prompt or rewritten query names a configured `[prompt_hook.projects]` code mapped in `[scopes]`, those scope matchers union additively with the current repo and apply automatic `scope:<path>` bias (`+0.3` via `BIAS_BOOST`) on both the Haiku and local paths so cross-repo project notes surface without dropping local matches (opt out of automatic scope bias with `default_bias = ["relevance"]` under `[query]`). On scopes with at least 20 active items, the Haiku path drops low-information hits whose matched-term IDF sum falls below `[prompt_hook] min_idf` (default `3.0`; `0.0` disables via `run_query`; exact ref hits bypass; dropped IDs log under `floor_dropped`). The local fallback applies `[prompt_hook] local_min_idf` (default `8.0`; `0.0` disables) as its local IDF floor on the same scopes, so both floors start at 20 active items. Disable per invocation with `SM_PROMPT_HOOK=0`.
  120. ### MCP server (`sm mcp`)
  121. Speaks JSON-RPC 2.0 over stdio (`MCP 2026-07-28` stateless metadata and `2024-11-05` through `2025-11-25` `initialize` handshakes) and serves eight tools:
  122. | Tool | Arguments | Purpose |
  123. |---|---|---|
  124. | `memory_query` | `query`; optional `bias`, `kind`, `tag`, `source`, `since`, `until`, `recent`, `include_history`, `in`, `limit`, `all_repos`, `repo` | Ranked search (`sm query --format json`); `bias` accepts `scope:<path>` |
  125. | `memory_list` | optional `limit`, `offset`, `kind`, `tag`, `source`, `since`, `until`, `status`, `include_history`, `all_repos`, `repo`, `in` | Browse items newest-first without a query |
  126. | `memory_show` | `ids` (non-empty array) | Full body, refs, and provenance per ID |
  127. | `memory_related` | `id`; optional `limit` | Supersede chain, shared refs, same session |
  128. | `memory_put` | `text`, `tag`; optional `kind`, `evidence`, `refs`, `supersedes`, `repo` | Store item, redact secrets, warn on overlaps |
  129. | `memory_amend` | `id`; optional `text`, `title`, `kind`, `tag`, `evidence`, `repo`, `add_refs`, `remove_refs`, `refs`, `add_tags`, `remove_tags`, `tags`, `as_of` | Append-only update (creates a new item and supersedes `id`) |
  130. | `memory_retire` | `id`; optional `reason` | Soft-retire an active item with no replacement |
  131. | `memory_supersede` | `old_id`, `new_id` | Retire `old_id` in favor of `new_id` |
  132. ## Ontology and retrieval gate
  133. `simple-memory` organizes notes in a two-layer ontology:
  134. - **Layer 1 (SQLite `items` columns)**: every item stores `kind` (`fact`, `decision`, `learning`, `episode`, `task`, `handoff`), evidence `tag` (`executed`, `verified`, `decided`, `client-stated`, `derived`, `assumed`, `prior`, `planned`), `repo`, extracted `refs`, and `source` provenance.
  135. - **Layer 2 (config `[scopes]` tree)**: `~/.simple-memory/config.toml` groups repos and case-sensitive whole-word project codes (such as `"GLX"`) into a slash-separated hierarchy (company, client, project levels) with automatic ancestor roll-up.
  136. Both prompt-hook recall (`sm hook prompt`) and explicit lookup (`sm query` / `sm mcp`) converge on the same SQL filter, FTS5 + ref candidate pool, and rank/bias gate:
  137. ![Ontology and retrieval gate](assets/ontology.svg)
  138. - **Hard scope filter (`--in`)**: `sm query "auth timeout" --in acme/globex` searches across all repos and keeps only items matching `acme/globex` or its descendants.
  139. - **Soft scope bias (`--bias scope:<path>`)**: `sm query "auth timeout" --bias scope:acme/globex` (or MCP `memory_query` `bias`, or `[query] default_bias`) keeps the normal repo result set, widens the FTS candidate pool to `100`, and adds `+0.3` (`BIAS_BOOST`) per matched scope without overriding exact `ref_hits`, `phrase`, or `accent` matches (reported as `why=...,bias:scope:acme/globex`). When `--bias` contains only `scope:<path>` tokens, they merge additively on top of `[query] default_bias` so durable kind, tag, and recency boosts stay active; pass `relevance` or another explicit kind/tag token (such as `--bias relevance,scope:acme/globex`) to replace the defaults. Stack parent and child paths (`--bias scope:acme,scope:acme/globex`) for hierarchical specificity.
  140. - **Automatic hook scope bias**: When `sm hook prompt` matches a `[prompt_hook.projects]` code to `[scopes]`, matched paths union additively into SQL and apply automatic `scope:<path>` bias on both the Haiku and local paths. Set `default_bias = ["relevance"]` under `[query]` to opt out of automatic scope bias (along with recency and kind/tag bias) while keeping additive SQL scope inclusion.
  141. ## Multi-repo scopes and maintenance
  142. Group related repos or project codes locally in `~/.simple-memory/config.toml`: add the lines under the `[scopes]` header that `sm init` already wrote (a second `[scopes]` header breaks every command):
  143. ```toml
  144. # under the existing [scopes] header
  145. "acme" = ["repo:acme-internal"]
  146. "acme/globex" = ["GLX"]
  147. "acme/globex/portal" = ["repo:globex-portal"]
  148. ```
  149. Filter hard across scopes with `sm query "auth timeout" --in acme/globex`, soft-boost a scope without filtering via `sm query "auth timeout" --bias scope:acme/globex`, and inspect active, superseded, and retired store counts, recall open rates, catch-up runs, and scope totals with `sm stats` (`--days N`, `--format json`).
  150. Check store health anytime:
  151. ```sh
  152. sm doctor --imports # check DB integrity and list unimported task logs, handoffs, memory files
  153. sm upkeep --report # read-only report of near-duplicates and stale planned/assumed items
  154. sm backup # verified SQLite backup copy in ~/.simple-memory/backups/
  155. ```
  156. A copy made by hand with `sm backup` has the same `memory-<time>-auto.db` name as the automatic ones, so `--keep N` (default 7) and catch-up rotate it too: copy a file you want to keep somewhere else. To restore, move `memory.db` (and any `memory.db-wal` and `memory.db-shm` beside it) aside, then copy the backup file to `memory.db`.
  157. ## Extending simple-memory
  158. Modules follow a downward architecture (`cli` -> `service` -> `store` / `sources` / `config` -> `core`, plus shared `py`, `clock`, `error`), with three explicit helper edges (`rust/src/config.rs` -> `service::capture`, `rust/src/config.rs` -> `service::query::LOCAL_TAU`, and `rust/src/config.rs` -> `sources`; `stands_as_word` lives in `rust/src/core/terms.rs`):
  159. - **Custom stopwords and ranking defaults**: Set `extra_stopwords` under `[prompt_hook]` for domain/language filler skipped by the local fallback, and `default_bias` under `[query]` to override default ranking without recompiling.
  160. - **New import source**: Add a parser under `rust/src/sources/` returning `core::item::Item` records, register its subcommand in `rust/src/cli/args.rs` and `rust/src/service/import_.rs`, and wire it into `rust/src/service/catchup.rs` + `rust/src/service/doctor.rs` (`--imports`).
  161. - **New MCP tool or schema field**: Add tool schemas and handlers in `rust/src/service/mcp.rs` over shared `service/*` calls; place numbered `.sql` migrations under `rust/migrations/` and register them in `rust/src/store/connect.rs`.
  162. - **Additional redaction patterns**: Extend `rust/src/core/redact.rs` with linear-time regex patterns and unit tests.
  163. <details>
  164. <summary>CLI command reference</summary>
  165. | Command | Summary |
  166. |---|---|
  167. | `sm init` | Create home dir, `memory.db`, and commented `config.toml` |
  168. | `sm config` | Print effective configuration (defaults plus `config.toml`) as TOML |
  169. | `sm put TEXT --tag TAG [...]` | Store item (`--kind`, `--evidence`, `--refs`, `--tags`, `--supersedes`, `--repo`, `--as-of`) |
  170. | `sm query TEXT [...]` (alias `sm search`) | Ranked search with unquoted terms, `-term`/`-"phrase"` exclusions, relative `--since`/`--until` (`30m`, `24h`, `7d`, `2w`), additive `--bias scope:<path>`, `--limit`, `--recent`, `--kind`, `--tag`, `--source`, `--in` (mutually exclusive with `--repo`), `--all`, `--include-history`, `--format` |
  171. | `sm show ID [ID ...] [--format text\|json]` | Print full text and provenance (`text` or `json` array); exits 1 if any ID is missing |
  172. | `sm related ID [...]` | Show supersede chain, shared-ref items, and same-session items |
  173. | `sm supersede OLD NEW` | Mark `OLD` superseded by `NEW` |
  174. | `sm retire ID [--reason TEXT]` | Soft-retire an active item with no replacement (default reason: `manual`) |
  175. | `sm amend ID [...]` | Append-only update: create a new item with changed fields and supersede `ID` atomically |
  176. | `sm list [...]` | Browse items newest-first without a query (`--limit`, `--offset`, `--repo \| --all \| --in`, `--kind`, `--tag`, `--source`, `--since`, `--until`, `--status \| --include-history`, `--format`) |
  177. | `sm import tasklog\|handoff\|legacy\|proposal PATH` | Import YAML task logs, Markdown handoffs, legacy DBs, or proposal JSONL (`--apply`, `--dry-run`) |
  178. | `sm import automemory \| sessions \| jsonl \| catch-up` | Sync Claude memory files, summarize idle sessions, import JSONL, or run full catch-up |
  179. | `sm export [--include-history] [--repo R \| --all]` | Dump items sorted by ID as JSONL to stdout |
  180. | `sm upkeep [--dry-run] [--report]` | Retire older/claimed session handoffs; `--report` flags near-duplicates and stale items |
  181. | `sm backup [--keep N]` | Checked SQLite backup in `backups/` |
  182. | `sm doctor [--rebuild-fts] [--backfill-refs] [--imports]` | Verify SQLite integrity, rebuild FTS5, backfill refs, or audit unimported files |
  183. | `sm stats [--days N] [--format text\|json]` | Store counts (active, superseded, retired), recall open rate, catch-up runs, backups, and `[scopes]` rollup |
  184. | `sm hook prompt [--agy]` | Harness hook reading prompt JSON on stdin |
  185. | `sm hooks print claude-code\|agy\|mcp` | Print harness configuration JSON to stdout |
  186. | `sm mcp` | Run JSON-RPC 2.0 MCP server on stdio |
  187. | `sm update [--check]` | Check npm for a newer release and upgrade npm installs (or print the source-upgrade command) |
  188. | `sm --version`, `sm -v` | Print installed binary version |
  189. </details>
  190. <details>
  191. <summary>Import file formats and catch-up counters</summary>
  192. - **Task log**: a YAML file under `<root>/<repo>/docs/tasklog/<folder>/`, where `<root>` is a `[upkeep] tasklog_roots` entry and `<repo>` is one to three folders below it (`sm import tasklog PATH` takes a file, or a folder and every `.yaml` below it). Fields: `id` (default: file name), `title`, `repo` (default: the folder above `docs`), `state` (kept as a tag), `as_of` (default: file time), `results`, `directions`, `open` and `next` (a list or text; they make the body), `commits` (tag `executed`, the commits as evidence; with none the tag is `derived`), `continues`, `superseded_by`. A named import stores the good files, names each bad file and exits 1.
  193. - **Handoff**: every `.md` file in or below a `[upkeep] handoff_dirs` entry is stored as a handoff. The title is the first `# ` line of the first 20 lines (a `HANDOFF:` prefix is dropped; none: the file name). A `Written: <ISO time>` line there sets `as_of` (missing or invalid: file time). The repo comes from the folder that holds the file (a Claude Code project folder or scratchpad) or from a `CWD: <path>` line, matched against `[repos] roots` (no match: `unassigned`); a `Repo:` line is not read. The body keeps only the `##` and `###` sections headed Request, Done, Recap, Decision(s), Accomplished, What changed, Results, Open or Next (a heading that starts with one of these words counts); other sections, `### State` included, are dropped. With no such heading the whole file is the body.
  194. Counters that `sm import catch-up` (one line per part), `sm doctor --imports` and `sm upkeep` print:
  195. | Counter | Meaning |
  196. |---|---|
  197. | `not_stored` | files with no item yet, or whose body changed since the import |
  198. | `inserted` | items stored in this run |
  199. | `failed_rows` | files or rows that could not be imported (`sm doctor --imports` names the files) |
  200. | `unreadable` | files that could not be parsed |
  201. | `unmapped` | memory files, or sessions, whose folder maps to no repo (set `[repos] roots`) |
  202. | `stored_tasks_without_file`, `stored_without_file` | active items whose file is gone |
  203. | `added`, `updated`, `retired`, `unchanged` | memory files: new item, changed item, item retired because its file is gone, no change |
  204. | `made`, `deleted`, `items` | backup: copies made, old copies removed, items in the copy |
  205. | `sessions`, `superseded` | upkeep: sessions that had older handoffs, handoffs retired for the newest one |
  206. | `handoffs_without_session` | active handoffs whose file name holds no session id; upkeep cannot pair them, and prints this on every run |
  207. | `scanned`, `unchanged`, `active` | sessions: transcripts read, already seen, still in use |
  208. | `headless`, `light`, `covered` | sessions that need no card: no prompt, few prompts and no commit, an item already covers it |
  209. | `candidates`, `carded`, `plain` | sessions: cards wanted, cards stored, cards made without Haiku |
  210. | `candidates`, `retired`, `in_worktree`, `on_branch`, `no_folder` | retire_missing: task items whose file is gone; retired; kept because the file is in another checkout or on a branch; repo folder not found |
  211. | `deleted` | prune: hook state files older than 14 days removed |
  212. </details>
  213. <details>
  214. <summary>Configuration and environment variables</summary>
  215. `sm init` writes a commented template to `~/.simple-memory/config.toml` and never overwrites an existing file. The template already holds every section header below; to change a key, remove the `# ` before it under its header, and never add a second header. `sm doctor` reports a config that does not parse and exits 1; `sm config`, `sm doctor` and `sm import catch-up` name an unknown section or key on stderr.
  216. - `[repos] roots`: Parent directories whose direct children map workspace/transcript folders to repo keys (`[repo_aliases]` maps aliases such as worktrees).
  217. - `[keyword_aliases]`: Query term expansions (e.g. `"k8s" = "kubernetes"`).
  218. - `[query] default_bias`: Default is `["recency", "fact", "decision", "learning", "executed", "verified", "decided", "client-stated"]`. Accepts the same tokens as `--bias`, including `scope:<path>` (for example `"scope:acme/globex"`). Explicit `--bias` with only `scope:<path>` tokens merges on top of `default_bias`; set `["relevance"]` to disable recency, kind/tag, and automatic prompt-hook scope bias.
  219. - `[prompt_hook]`: `enabled`, `model` (`"haiku"` or `"none"`), `timeout`, `limit`, `claude_bin`, `extra_stopwords`, `min_idf` (default `3.0`; `0.0` disables), `local_min_idf` (default `8.0`; `0.0` disables), and `[prompt_hook.projects]` project codes.
  220. - `[catch_up]`: `enabled`, `interval_minutes` (default `10`).
  221. - `[upkeep]`: `tasklog_roots` and `handoff_dirs`.
  222. - `[capture]`: `enabled`, `root` (`~/.claude/projects`), `idle_minutes`, `since_days`, `min_prompts`, `max_per_run`, `model`, `timeout`, `dialogue_chars`.
  223. - `[automemory]`: `enabled`, `root` (`~/.claude/projects`).
  224. - `[scopes]` and `[backup]`: Path matchers plus backup `interval_hours` (`24`) and `keep` (`7`).
  225. Environment variables:
  226. - `SIMPLE_MEMORY_HOME`: Override `~/.simple-memory`.
  227. - `SM_UTC_OFFSET`: Explicit offset (`+00:00`, `-05:00`, `Z`, `+0530`) overriding OS local timezone (`localtime_r`).
  228. - `SM_PROMPT_HOOK=0`: Disable prompt-hook recall and background catch-up for one process tree (such as subagent runs).
  229. - `SM_BINARY_PATH`: Explicit path to a `sm` binary for the npm wrapper; exits with an error if the path does not exist instead of falling back.
  230. - `SM_SKIP_DOWNLOAD=1`: Skip the npm `postinstall` GitHub Release binary fallback download.
  231. - `SM_NO_UPDATE_CHECK=1`: Disable the npm wrapper's 24-hour interactive update reminder.
  232. </details>
  233. <details>
  234. <summary>Privacy, redaction, and limits</summary>
  235. - **Local by default**: Everything stays in your local `memory.db`. Model calls run only when Claude Haiku is invoked through your local `claude -p` for `[prompt_hook]` query distillation or `[capture]` session cards (disable either in `config.toml`).
  236. - **Automatic write redaction**: `put_item` and `put_items_batch` strip `<private>...</private>` blocks and replace known secret shapes (private keys, cloud access keys, API tokens such as `sk-`/token prefixes, JWTs, bearer tokens, signed URL query parameters, URL credentials, and `password=`-style assignments) with `[REDACTED:<kind>]` before SQLite insert.
  237. - **Redaction limits**: Redaction is pattern-based and best effort; a credential URL is caught in the `user:password@` form, including an empty user (`redis://:password@host`), a `/` in the password after a user without a dot, and a known token shape (such as an AWS access key id) as the user or in the password next to a `/`. It is not caught when the password holds a quote, when a bare token stands alone as the user part with no known token shape, or, unless the user is a known token shape, when the user holds a dot and the password a `/`, when the password starts with `/` or has only digits before its first `/`, or when it holds both `:` and `/`; text of the form `scheme://word:word/path@suffix` on a host without a dot (such as an scp-style path inside an `ssh://` URL) is replaced as if it were a credential.
  238. - **Known limits**: Search is lexical/prefix-based with configurable `[keyword_aliases]` rather than semantic embeddings; multi-machine sync is manual (copy `memory.db` or files under `backups/`).
  239. </details>
  240. <details>
  241. <summary>Development and testing</summary>
  242. Run all checks with `HOME` and `SIMPLE_MEMORY_HOME` pointed at an empty scratch directory (preserving `RUSTUP_HOME` and `CARGO_HOME`):
  243. ```sh
  244. cd rust
  245. cargo fmt --check
  246. cargo build --release --locked
  247. cargo clippy --all-targets --locked -- -D warnings
  248. cargo clippy --all-targets --locked --features parity -- -D warnings
  249. mkdir -p /tmp/sm-test/.simple-memory
  250. env RUSTUP_HOME="${RUSTUP_HOME:-$HOME/.rustup}" CARGO_HOME="${CARGO_HOME:-$HOME/.cargo}" \
  251. HOME=/tmp/sm-test SIMPLE_MEMORY_HOME=/tmp/sm-test/.simple-memory \
  252. cargo test --locked --features parity --no-fail-fast
  253. cd ..
  254. TMPDIR=/tmp bash scripts/dead_code_scan.sh rust
  255. TMPDIR=/tmp bash scripts/smoke.sh rust/target/release/sm
  256. TMPDIR=/tmp bash scripts/test_scripts.sh
  257. node --test npm/test/npm_wrapper.test.mjs
  258. ```
  259. Note: Avoid colons (`:`) inside scratch `HOME` paths on macOS (`DYLD_FALLBACK_LIBRARY_PATH` treats `:` as a path separator); test custom timezone offsets via `SM_UTC_OFFSET=+05:30`.
  260. </details>
  261. ## License
  262. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.