memory: polish help and docs (#569)

- add /memory help and clearer invalid-subcommand guidance
- register /memory in shared slash-command help
- align memory docs with current behavior and config
- add focused tests for help and discovery

docs/CONFIGURATION.md

@@ -128,6 +128,7 @@ These override config values:
 - `DEEPSEEK_SKILLS_DIR`
 - `DEEPSEEK_MCP_CONFIG`
 - `DEEPSEEK_NOTES_PATH`
+- `DEEPSEEK_MEMORY` (`1|on|true|yes|y|enabled` turns user memory on)
 - `DEEPSEEK_MEMORY_PATH`
 - `DEEPSEEK_ALLOW_SHELL` (`1`/`true` enables)
 - `DEEPSEEK_APPROVAL_POLICY` (`on-request|untrusted|never`)
@@ -320,6 +321,11 @@ If you are upgrading from older releases:
   used immediately by `/mcp`, but rebuilding the model-visible MCP tool pool
   requires restarting the TUI.
 - `notes_path` (string, optional): defaults to `~/.deepseek/notes.txt` and is used by the `note` tool.
+- `[memory].enabled` (bool, optional): defaults to `false`. When `true`,
+  the TUI loads the user memory file into a `<user_memory>` prompt block,
+  enables `# foo` quick-capture in the composer, surfaces the `/memory`
+  slash command, and registers the `remember` tool. The same toggle is
+  available via `DEEPSEEK_MEMORY=on`.
 - `memory_path` (string, optional): defaults to `~/.deepseek/memory.md`.
   Used by the user-memory feature when enabled — see
   [`MEMORY.md`](MEMORY.md) for the full feature surface (`# foo`
@@ -369,6 +375,31 @@ If you are upgrading from older releases:
 - `hooks` (optional): lifecycle hooks configuration (see `config.example.toml`).
 - `features.*` (optional): feature flag overrides (see below).
 
+### User memory
+
+User memory is split across one top-level path setting and one opt-in
+toggle table:
+
+```toml
+memory_path = "~/.deepseek/memory.md"
+
+[memory]
+enabled = true
+```
+
+Notes:
+
+- `memory_path` stays at the top level beside `notes_path` and
+  `skills_dir`; it is not nested under `[memory]`.
+- `DEEPSEEK_MEMORY_PATH` overrides the file path from the environment.
+- `DEEPSEEK_MEMORY=on` (also `1`, `true`, `yes`, `y`, or `enabled`)
+  flips the feature on without editing `config.toml`.
+- The feature is inert when disabled: no file is injected, `# foo`
+  falls through to normal message submission, and the model does not
+  see the `remember` tool.
+- See [`MEMORY.md`](MEMORY.md) for examples and the full `/memory`
+  command surface.
+
 ### Parsed but currently unused (reserved for future versions)
 
 These keys are accepted by the config loader but not currently used by the interactive TUI or built-in tools:

docs/MEMORY.md

@@ -20,6 +20,9 @@ Either set the env var:
 export DEEPSEEK_MEMORY=on
 ```
 
+Accepted truthy values are `1`, `on`, `true`, `yes`, `y`, and
+`enabled`.
+
 …or add to `~/.deepseek/config.toml`:
 
 ```toml
@@ -31,7 +34,25 @@ Restart the TUI after toggling. Disabling is the same in reverse.
 
 The memory file lives at `~/.deepseek/memory.md` by default; override
 with `memory_path` in `config.toml` or `DEEPSEEK_MEMORY_PATH` in
-the environment.
+the environment. `DEEPSEEK_MEMORY_PATH` wins over the config file when
+both are set.
+
+## Quick examples
+
+```text
+# remember that this repo prefers cargo fmt before commits
+/memory
+/memory path
+/memory edit
+/memory help
+```
+
+- Type `# remember that this repo prefers cargo fmt before commits` in
+  the composer to append a timestamped bullet without firing a turn.
+- Run `/memory` to confirm where the feature is writing and what is
+  currently stored.
+- Run `/memory edit` when you want to groom the file manually in your
+  editor.
 
 ## What gets injected
 
@@ -84,11 +105,18 @@ Inspect, clear, or get hints about editing the file:
 | `/memory path`      | Print just the resolved path                          |
 | `/memory clear`     | Replace the file with an empty marker                 |
 | `/memory edit`      | Print the `${VISUAL:-${EDITOR:-vi}} <path>` shell line |
+| `/memory help`      | Show command-specific help and the current path       |
 
 The `/memory edit` form intentionally just prints the command rather
 than spawning the editor in-process — that keeps the slash-command
 handler simple and consistent regardless of which editor you use.
 
+You can also discover the feature from the general help surfaces:
+
+- `/help memory` shows the slash-command summary and usage line.
+- `/memory help` prints the memory-specific subcommands plus the
+  resolved path.
+
 ### 3. The `remember` tool (auto-update, #489)
 
 When memory is enabled the model gets a `remember` tool with this
@@ -134,6 +162,22 @@ about the timestamp format; it just reads the whole file as the
 memory block. The timestamp is convention so you can tell when each
 note was added when grooming the file.
 
+## Hierarchy and imports
+
+Memory is intentionally **user-scoped** rather than repo-scoped. It
+sits alongside — not inside — project instruction sources such as
+`AGENTS.md`, `.deepseek/instructions.md`, and `instructions = [...]`.
+
+- Use **memory** for durable personal preferences that should follow
+  you across repos and sessions.
+- Use **project instructions** for repo-specific conventions that
+  should travel with the codebase.
+
+The memory loader currently reads one resolved file path verbatim.
+`@path` imports / includes are **not** supported today; if you need a
+larger reusable instruction bundle, put it in a project instruction
+file or a skill instead.
+
 ## What stays out of memory
 
 Memory is for **durable** signal. Things that should NOT live there: