Skip to content
Back to search

ai-memory

ai-memory plugins: lifecycle capture and memory tools for coding agents, backed by your own ai-memory server.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/akitaonrails--ai-memory"><img src="/api/listings/akitaonrails--ai-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.

These steps run a script from the network that findsafeskills does not scan.

Linux and macOS (two commands, no root)

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

`install.sh` downloads the release for your OS and CPU, checks it against the release's published SHA-256 checksum (it refuses to install without a match), and links `~/.local/bin/ai-memory`. `ai-memory setup` then creates the data directory with a bearer token in an owner-only file, starts a per-user service (systemd `--user` or a launchd LaunchAgent), and wires MCP, hooks and Agent Skills for every agent it finds, or the ones you name with `--agent`. It shows the plan, with where it found each agent, and asks first: answer `y`, or type the numbers of the agents to wire. `--plan` prints the plan and changes nothing, `--web` shows the plan as a page in your browser and applies the agents you tick there, `--yes` skips the question, and running it again changes nothing. Afterwards, restart your agents and ask one of them "What do you remember about this project?" to see it answer through ai-memory. Details, the environment variables and how to verify the script before running it are in [`docs/install.md`](docs/install.md#one-step-native-install-installsh--ai-memory-setup). An AI agent installing ai-memory for you can follow [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).

Claude Code and Codex users can wire their agent as a marketplace plugin instead (the binary is still installed as above):

claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory
codex plugin marketplace add akitaonrails/ai-memory && codex plugin add ai-memory@ai-memory

Codex then asks you to trust the hooks in `/hooks`. See [Marketplace plugins](docs/install.md#marketplace-plugins).

Windows (two commands, no admin)

In PowerShell:

irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
ai-memory setup

`install.ps1` checks the release zip against its published SHA-256 checksum, unpacks it under `%LOCALAPPDATA%\Programs\ai-memory` and adds that directory to your user `PATH`. `ai-memory setup` then does what it does on Linux and macOS, with a logon entry in place of the service: the server starts when you sign in, with no console window, and restarts if it fails. Details and the other Windows setups (WSL2, Docker Desktop, a real Windows service) are in [`docs/windows.md`](docs/windows.md).

With [Scoop](https://scoop.sh) (ai-memory 3.4.0 or later):

scoop bucket add akitaonrails https://github.com/akitaonrails/scoop-bucket
scoop install ai-memory
ai-memory setup

Update it with `scoop update ai-memory`.

Arch Linux (AUR)

For native Arch installs, use the AUR packages. They install `/usr/bin/ai-memory`, packaged hook sources, and both system-level and user-level systemd units.

yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source
ai-memory setup         # data dir, user service, agents, self-check

Homebrew (macOS and Linux)

The tap installs the prebuilt binary and its hook sources on macOS and on Linux, including atomic distributions such as Bazzite or Fedora Silverblue where Homebrew is the usual way to add tools:

brew install akitaonrails/tap/ai-memory
ai-memory setup         # data dir, user service, agents, self-check

Use either `ai-memory setup` or `brew services start ai-memory`, not both. Details are in [`docs/install.md`](docs/install.md#homebrew-macos-and-linux).

Fedora (RPM)

Download the `x86_64` or `aarch64` RPM from the [latest release](https://github.com/akitaonrails/ai-memory/releases/latest), then install it:

sudo dnf install ./ai-memory-*.rpm

On a single-user workstation, `ai-memory setup` then does the rest, as on the two-command path above: data dir and token, a user service, the agents it finds, and a self-check.

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.

.claude-plugin/marketplace.json · Manifest · 21 lines
  1. {
  2. "name": "ai-memory",
  3. "owner": {
  4. "name": "AkitaOnRails",
  5. "url": "https://github.com/akitaonrails"
  6. },
  7. "description": "ai-memory plugins: lifecycle capture and memory tools for coding agents, backed by your own ai-memory server.",
  8. "plugins": [
  9. {
  10. "name": "ai-memory",
  11. "description": "Long-term memory across sessions and harnesses.",
  12. "version": "3.5.0",
  13. "source": {
  14. "source": "git-subdir",
  15. "url": "https://github.com/akitaonrails/ai-memory.git",
  16. "path": "plugins/claude-code",
  17. "ref": "v3.5.0"
  18. }
  19. }
  20. ]
  21. }
README.md · README · 840 lines · 3 findings marked
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/logo-dark.png">
  4. <img alt="ai-memory" src="docs/logo-light.png" width="480">
  5. </picture>
  6. </p>
  7. > Long-term memory for AI coding agents. Quit Claude Code mid-task,
  8. > start OpenAI Codex in the same directory, continue without
  9. > re-explaining the architecture, the failed approaches, or the open
  10. > questions.
  11. **Website: [aimemory.sh](https://aimemory.sh)**
  12. [![Website](https://img.shields.io/badge/website-aimemory.sh-blue)](https://aimemory.sh)
  13. [![Release](https://img.shields.io/github/v/release/akitaonrails/ai-memory)](https://github.com/akitaonrails/ai-memory/releases/latest)
  14. [![Rust](https://img.shields.io/badge/rust-1.95+-blue)](rust-toolchain.toml)
  15. [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  16. ## Why ai-memory
  17. Your coding agent probably has a memory feature already. Claude Code takes its
  18. own notes, Cursor remembers some things, and every platform is adding more. They
  19. all have the same limits: the notes live on one machine, belong to one agent,
  20. and drop out of view when you switch tools or hand the work to a teammate.
  21. ai-memory removes those limits.
  22. - **It follows you across agents.** More than twenty harnesses (Claude Code,
  23. Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and others)
  24. feed one shared memory. Quit Claude Code mid-task, open Codex in the same
  25. directory, and the next agent picks up a handoff that says where you left
  26. off, what failed, and what is still open. Handoffs are a typed protocol:
  27. each one has an owner and is claimed exactly once.
  28. - **It can carry the session, not just a summary.** Start agents with
  29. `ai-memory run`: quit Claude Code, run `ai-memory run codex`, and Codex gets
  30. the shared workstream plus a private, temporary local projection of Claude's
  31. visible native history for exact details the bounded startup packet omitted.
  32. The remote server receives only the harness and session identity, never the
  33. local transcript path or body. Direct harness launches behave exactly as
  34. before.
  35. - **It follows you across projects.** A small profile of how you usually
  36. work (your package manager, test layout, architecture habits) reaches
  37. every new repository at session start, so you stop re-explaining yourself.
  38. It sits below each repository's rules file as a default. It is on by
  39. default for a single user, and on a shared server it is opt-in and private
  40. per person. See [`docs/cross-project-profile.md`](docs/cross-project-profile.md).
  41. - **It follows you across machines.** Memory lives in a server you run, on
  42. the same laptop, a homelab box, or anywhere else, so the project you left
  43. on the desktop is the project you resume on the laptop, with the same
  44. knowledge and the same open questions.
  45. - **It works for a team.** Point everyone at one server, and what one
  46. person's sessions learn, everyone's agents can retrieve. Knowledge is
  47. shared per project; personal handoffs stay personal. Multi-user auth,
  48. per-person attribution, and an audit log are built in and are not a paid tier.
  49. - **Your memory is plain markdown.** The source of truth is a git-backed
  50. wiki of ordinary `.md` files: `grep` it, open it in Obsidian, edit it by
  51. hand, `rsync` it. The database is a derived index that can always be
  52. rebuilt from the files. There is no vector store to maintain and no
  53. content locked in a binary blob.
  54. - **It captures the work itself, silently.** Lifecycle hooks record what
  55. happened (prompts, tool calls, session boundaries), sanitize it at a typed
  56. privacy boundary before anything is stored, and the server consolidates it
  57. into readable pages. You do not have to ask it to remember anything. The
  58. default path uses **zero LLM calls**: capture, search, and handoffs all
  59. work with no API key.
  60. - **It ages memory without an LLM.** Memory decays on a schedule you can
  61. tune per tier, and memory you use decays *slower*: opening a page,
  62. searching it, or reaching it through a link counts as use. When episodic
  63. notes go cold they can be compacted down to their durable facts (file
  64. paths, error codes, decisions) instead of dropped. Near-duplicates
  65. collapse into one, and likely contradictions get flagged, all with **zero
  66. API calls**. Nothing is hard-deleted: the original stays in git and the
  67. version chain (`restore-page` brings it back). Access-weighted retention is
  68. always on because it can only keep memory *longer*. The parts that rewrite
  69. or drop content (compaction, dedup, per-tier curves) stay off by default
  70. until you turn them on.
  71. - **It can also "dream", if you let it.** With an LLM configured, an opt-in
  72. background pass rewrites whole clusters of cold notes into single coherent
  73. pages while you are idle, and cancels as soon as you come back to work. It
  74. never deletes a source (the pre-merge versions stay reachable), it is off
  75. by default, and it has to pass a recall eval before it could become
  76. default behavior. Unless you ask for more, the zero-LLM path above is what
  77. runs.
  78. - **It is honest about itself.** It ships as one self-contained binary.
  79. Purge commands say exactly what "deleted" means. The write ceiling
  80. (~700/s) is measured, not guessed. An audit log records every mutation.
  81. ## How it works
  82. ```
  83. capture ──▶ consolidate ──▶ recall ──▶ handoff
  84. hooks session-end search next agent,
  85. observe summaries as + brief any harness
  86. silently wiki pages injection
  87. ```
  88. Agents emit sanitized observations through lifecycle hooks as you work.
  89. At session end, observations become coherent markdown pages in the
  90. project's wiki (optionally LLM-written; useful even without). The next
  91. session, in any agent on any machine, gets a bounded brief and can search
  92. everything: full-text, entities, links, and (optionally) vectors, fused
  93. into one ranking. Cross-agent handoffs pass the baton explicitly.
  94. The full design, including the invariants that keep multi-user and
  95. multi-session use safe, is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
  96. An optional [server-rendered management console](docs/management-ui.md) provides
  97. user administration, session inspection and deletion, and personal MCP API keys.
  98. Build with `--features management-ui` and start `serve --transport http
  99. --enable-management-ui`; both compile-time and runtime opt-ins are required.
  100. ## Support matrix
  101. Every row below is a first-party integration (MCP registration, lifecycle
  102. hooks, or both) checked by CI. The full matrix with per-agent notes and
  103. caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).
  104. | Area | Status |
  105. | --- | --- |
  106. | Linux | Supported |
  107. | NixOS module | Supported |
  108. | macOS | Supported |
  109. | Windows via WSL2 | Supported |
  110. | Native Windows | Experimental |
  111. | Claude Code | Supported |
  112. | Codex | Supported |
  113. | Command Code | Supported |
  114. | Devin CLI | Supported |
  115. | OpenCode (V1/V2 auto-detected; legacy force-V2 aliases retained) | Supported |
  116. | Cursor | Supported |
  117. | Gemini CLI | Supported |
  118. | Oh My Pi / OMP | Supported |
  119. | Pi | Supported |
  120. | Crush | Managed-only |
  121. | Managed workstreams | Opt-in |
  122. | Claude Desktop | MCP-only |
  123. | OpenClaw | Supported |
  124. | Antigravity CLI | Supported |
  125. | Grok Build CLI | Supported |
  126. | Swival CLI | MCP-only |
  127. | Zero | Supported |
  128. | ZCode | Supported |
  129. | Kimi Code | Supported |
  130. | Kiro CLI | Supported |
  131. | Pool | Hooks-only |
  132. | GitHub Copilot CLI | Supported |
  133. | Factory Droid | Supported |
  134. | Meta Muse Code | Supported |
  135. | CodeBuddy Code | Hooks-only |
  136. | WorkBuddy | Supported |
  137. | IBM Bob | Supported |
  138. | Qwen Code | Supported |
  139. | Qoder | Supported |
  140. | VS Code Copilot | MCP-only |
  141. | Zed | MCP-only |
  142. | DeepSeek Harness (DSH) | Hooks + MCP |
  143. | Cline CLI | Hooks + MCP |
  144. | FreeBuff | MCP-only |
  145. | Prime Agent | MCP-only |
  146. | Hermes Agent | Supported |
  147. | GrizzyBot | Supported |
  148. | LLM/auth providers | Supported |
  149. | Embedding providers | Supported |
  150. ## Coming from another tool?
  151. Most agent-memory tools optimize for one thing: extracting atomic facts per
  152. turn, a temporal knowledge graph, an agent-editable memory OS, or a hosted
  153. context API. ai-memory is built around a **git-backed markdown wiki as the
  154. source of truth**, with a derived index for retrieval. It captures
  155. automatically from lifecycle hooks, is shared across agents, machines, and
  156. people, and works with **zero LLM calls by default**. This table shows what
  157. carries over from each tool and what you gain:
  158. | Coming from… | What's similar | What you gain |
  159. |---|---|---|
  160. | **Mem0 / fact extractors** (LangMem) | Automatic per-turn capture | Memory compiles into readable **pages** you own and edit, not opaque fact rows; retrieval fuses FTS + entity + graph (+ local vectors) with no cloud API key |
  161. | **Zep / Graphiti** (temporal KG) | Temporal reasoning, typed relations | Bi-temporal-lite (`as_of`, version-filtered search) and typed edges without standing up a graph database, in one binary |
  162. | **mcp-memory-service** (fact rows, SQLite) | SQLite + local embeddings, hook capture, typed edges, honest numbers, and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging | Human-editable markdown **pages** instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done **zero-LLM by default, reversibly** (supersede-not-delete + `restore-page`), and **off by default** |
  163. | **basic-memory** (file-first markdown) | Markdown-on-disk as the source of truth | Automatic lifecycle capture and a derived FTS/entity/graph index on top, cross-agent handoffs, and multi-user sharing built in |
  164. | **Claude Code built-in memory** | "Remember my project" convenience, zero setup | Synced across machines and agents, searchable, team-capable, and captures tool lifecycle, unlike a per-laptop `MEMORY.md` |
  165. | **Hindsight / OpenViking** (LLM or VLM in the loop) | Living pages / document memory with a background consolidation loop, plus, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters | A self-contained binary that runs zero-LLM by default and keeps memory in markdown files that are the source of truth, not a mirror; claim-once handoffs; the dream/belief features are **opt-in, off by default, and never delete a source** (vs a mandatory LLM loop) |
  166. | **Supermemory / LiquidLM** (hosted memory API) | A managed second brain with automatic ingestion | Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing; ai-memory remembers *this repo*, not a general vault |
  167. Across all of these, ai-memory gives you files you own (git-backed markdown),
  168. a zero-LLM default, one self-contained binary, sharing across agents, machines,
  169. and teams, automatic lifecycle capture, and typed, claim-once handoffs.
  170. Opt-in features (LLM consolidation, vector search, the "dream" consolidation
  171. pass, belief-strength in ranking) stay opt-in, and the zero-LLM aging path
  172. (per-tier decay, extractive compaction, dedup, contradiction flagging,
  173. access-weighted retention) works with no API key at all.
  174. **Built on the shoulders of:** the
  175. [Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
  176. (compile-not-retrieve),
  177. [agentmemory](https://github.com/rohitg00/agentmemory) (hook capture for coding
  178. agents), [basic-memory](https://github.com/basicmachines-co/basic-memory)
  179. (markdown-on-disk truth),
  180. [cognee](https://github.com/topoteretes/cognee) (pipeline composition and
  181. triplet embeddings),
  182. [Hermes Agent](https://github.com/NousResearch/hermes-agent) (the
  183. self-improvement loop), and [A-MEM](https://arxiv.org/abs/2502.12110)
  184. (Zettelkasten-style atomic notes).
  185. The full comparison, covering where each approach wins, where ai-memory
  186. differs, and the published benchmark, is in [How ai-memory compares](docs/comparison.md).
  187. ## Quick start
  188. ### Linux and macOS (two commands, no root)
  189. ```bash
  190. curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 223 on GitHub
  191. ai-memory setup
  192. ```
  193. `install.sh` downloads the release for your OS and CPU, checks it against the
  194. release's published SHA-256 checksum (it refuses to install without a match),
  195. and links `~/.local/bin/ai-memory`. `ai-memory setup` then creates the data
  196. directory with a bearer token in an owner-only file, starts a per-user service
  197. (systemd `--user` or a launchd LaunchAgent), and wires MCP, hooks and Agent
  198. Skills for every agent it finds, or the ones you name with `--agent`. It shows
  199. the plan, with where it found each agent, and asks first: answer `y`, or type
  200. the numbers of the agents to wire. `--plan` prints the plan and changes
  201. nothing, `--web` shows the plan as a page in your browser and applies the agents
  202. you tick there, `--yes` skips the question, and running it again changes nothing.
  203. Afterwards, restart your agents and ask one of them "What do you remember
  204. about this project?" to see it answer through ai-memory. Details, the environment
  205. variables and how to verify the script before running it are in
  206. [`docs/install.md`](docs/install.md#one-step-native-install-installsh--ai-memory-setup).
  207. An AI agent installing ai-memory for you can follow
  208. [`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).
  209. Claude Code and Codex users can wire their agent as a marketplace plugin
  210. instead (the binary is still installed as above):
  211. ```bash
  212. claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory
  213. codex plugin marketplace add akitaonrails/ai-memory && codex plugin add ai-memory@ai-memory
  214. ```
  215. Codex then asks you to trust the hooks in `/hooks`. See
  216. [Marketplace plugins](docs/install.md#marketplace-plugins).
  217. ### Windows (two commands, no admin)
  218. In PowerShell:
  219. ```powershell
  220. irm https://github.com/akitaonrails/ai-memory/releases/latest/download/install.ps1 | iex
  221. ai-memory setup
  222. ```
  223. `install.ps1` checks the release zip against its published SHA-256 checksum,
  224. unpacks it under `%LOCALAPPDATA%\Programs\ai-memory` and adds that directory
  225. to your user `PATH`. `ai-memory setup` then does what it does on Linux and
  226. macOS, with a logon entry in place of the service: the server starts when you
  227. sign in, with no console window, and restarts if it fails. Details and the
  228. other Windows setups (WSL2, Docker Desktop, a real Windows service) are in
  229. [`docs/windows.md`](docs/windows.md).
  230. With [Scoop](https://scoop.sh) (ai-memory 3.4.0 or later):
  231. ```powershell
  232. scoop bucket add akitaonrails https://github.com/akitaonrails/scoop-bucket
  233. scoop install ai-memory
  234. ai-memory setup
  235. ```
  236. Update it with `scoop update ai-memory`.
  237. ### Arch Linux (AUR)
  238. For native Arch installs, use the AUR packages. They install
  239. `/usr/bin/ai-memory`, packaged hook sources, and both system-level and
  240. user-level systemd units.
  241. ```bash
  242. yay -S ai-memory-bin # prebuilt Linux x86_64/aarch64 binary
  243. yay -S ai-memory # builds from source
  244. ai-memory setup # data dir, user service, agents, self-check
  245. ```
  246. ### Homebrew (macOS and Linux)
  247. The tap installs the prebuilt binary and its hook sources on macOS and on
  248. Linux, including atomic distributions such as Bazzite or Fedora Silverblue
  249. where Homebrew is the usual way to add tools:
  250. ```bash
  251. brew install akitaonrails/tap/ai-memory
  252. ai-memory setup # data dir, user service, agents, self-check
  253. ```
  254. Use either `ai-memory setup` or `brew services start ai-memory`, not both.
  255. Details are in [`docs/install.md`](docs/install.md#homebrew-macos-and-linux).
  256. ### Fedora (RPM)
  257. Download the `x86_64` or `aarch64` RPM from the
  258. [latest release](https://github.com/akitaonrails/ai-memory/releases/latest),
  259. then install it:
  260. ```bash
  261. sudo dnf install ./ai-memory-*.rpm
  262. ```
  263. On a single-user workstation, `ai-memory setup` then does the rest, as on the
  264. two-command path above: data dir and token, a user service, the agents it
  265. finds, and a self-check.
  266. ```bash
  267. ai-memory setup
  268. ```
  269. System service installs use `/var/lib/ai-memory` and `/etc/ai-memory/` via the
  270. packaged unit. Full user-service, system-service, auth, and provider setup is in
  271. [`docs/install.md#arch-linux-native-packages-aur`](docs/install.md#arch-linux-native-packages-aur).
  272. ### macOS (menu bar app)
  273. A self-contained `.app` that bundles the native `ai-memory` binary and
  274. `hooks/` tree, starts the existing LaunchAgent, and opens `/web`,
  275. `ai-memory status`, and `config.toml` from the menu bar. Wiki, SQLite,
  276. config, and models stay in `~/Library/Application Support/ai-memory`, so
  277. replacing the app is an update and does not rewrite that tree.
  278. Needs a Rust toolchain and Xcode / Swift 6 (same as a source build):
  279. ```bash
  280. git clone https://github.com/akitaonrails/ai-memory
  281. cd ai-memory
  282. ./companions/ai-memory-macos/build.sh
  283. open "companions/ai-memory-macos/dist/AI Memory.app"
  284. ```
  285. Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**
  286. from the menu extra (no Dock icon). The app reads the bearer token `init`
  287. wrote into its data dir, so the status item turns green on its own. Then wire
  288. your agents with the bundled binary; `--no-service` leaves the app's
  289. LaunchAgent in charge:
  290. ```bash
  291. BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"
  292. "$BIN" setup --no-service
  293. ```
  294. Prebuilt tarball and launchd-without-the-app paths:
  295. [`docs/macos.md`](docs/macos.md). Companion details:
  296. [`companions/ai-memory-macos`](companions/ai-memory-macos).
  297. ### Docker
  298. You need: Docker or Podman + an agent CLI from the [Support Matrix](#support-matrix),
  299. or anything else that speaks MCP.
  300. The published Docker image includes `linux/amd64` and `linux/arm64` variants,
  301. so Apple Silicon Macs and ARM64 Linux hosts can pull `akitaonrails/ai-memory`
  302. without `--platform linux/amd64` emulation.
  303. The Docker quick-start below has **no authentication**: the container never
  304. runs `init`, so it starts without a token. The server binds to loopback only,
  305. so nothing outside the machine can reach it, but local processes and browser
  306. pages can. Native installs that run `ai-memory init` get a bearer token by
  307. default; see [Security](#security) below for that and for adding a token here.
  308. ```bash
  309. # 1. Install the ai-memory CLI wrapper (a small shell script that
  310. # runs the binary inside a container with your $HOME mounted). This is
  311. # the only thing that needs to live on the host filesystem.
  312. mkdir -p ~/.local/bin
  313. wrapper_tmp="$(mktemp -d)"
  314. trap 'rm -rf "$wrapper_tmp"' EXIT
  315. wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
  316. curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
  317. curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
  318. expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
  319. if command -v sha256sum >/dev/null 2>&1; then
  320. actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
  321. else
  322. actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
  323. fi
  324. [ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; }
  325. install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
  326. rm -rf "$wrapper_tmp"
  327. trap - EXIT
  328. # Most distros put ~/.local/bin on PATH automatically. If `which
  329. # ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:
  330. # export PATH="$HOME/.local/bin:$PATH"
  331. # 2. Start the server. `--restart unless-stopped` makes it come back
  332. # on docker daemon restart and on machine boot (provided your
  333. # docker service is enabled at boot — `sudo systemctl enable
  334. # docker` on most distros). Loopback-only bind (`127.0.0.1:49374`)
  335. # so nothing outside this machine can reach it. Omit the LLM /
  336. # EMBEDDING lines for zero-LLM mode — FTS5 search still works
  337. # without any keys.
  338. docker run -d --name ai-memory \
  339. --restart unless-stopped \
  340. -p 127.0.0.1:49374:49374 \
  341. -v ai-memory-data:/data \
  342. -e AI_MEMORY_LLM_PROVIDER=anthropic \
  343. -e ANTHROPIC_API_KEY=sk-ant-... \
  344. -e AI_MEMORY_EMBEDDING_PROVIDER=openai \
  345. -e OPENAI_API_KEY=sk-... \
  346. docker.io/akitaonrails/ai-memory:latest
  347. # 3. Wire your agent CLI in two commands. The wrapper takes care of
  348. # mounts and each client's config-path detection. Re-run with
  349. # `--agent codex`, `--agent command-code`, `--agent devin`, `--agent opencode`, `--agent opencode2`, `--agent gemini-cli`,
  350. # `--agent grok`, `--agent kimi-code`, `--agent kiro-cli`, `--agent copilot-cli`, `--agent droid`, `--agent muse`, `--agent cline`, `--agent qwen-code`, `--agent qoder`, `--agent omp`,
  351. # `--agent oh-my-pi`, `--client cursor`,
  352. # `--client gemini-cli`, `--client grok`, `--client kiro-cli`,
  353. # `--client cline`, `--client freebuff`, etc.
  354. # for additional agents; full list in docs/install.md.
  355. ai-memory install-mcp --client claude-code --apply
  356. ai-memory install-hooks --agent claude-code --apply
  357. ```
  358. On Linux and macOS, the Docker wrapper runs `install-hooks` through its
  359. checksum-verified native host client. Global options may precede the command,
  360. for example `ai-memory --config /path/to/config.toml run codex`; the native
  361. client receives the complete argument list. The installed hooks therefore enforce
  362. client-side capture controls such as `[capture] ignore_paths` and allowlist
  363. mode before an event reaches the spool or network. Set
  364. `AI_MEMORY_HOOK_PLATFORM=posix` explicitly only when you need the legacy shell
  365. compatibility path; the installer warns that path cannot enforce capture
  366. policy v1.
  367. The examples use `docker`; replace it with `podman` on a Podman host. The
  368. wrapper automatically uses Podman when Docker is not installed. Set
  369. `AI_MEMORY_DOCKER=podman` to force Podman when both engines are available.
  370. That completes the setup on Linux/macOS. Start a Claude Code session as
  371. usual: every prompt and tool call now lands in ai-memory, and the next session
  372. you open in this project will see a handoff with where you left off.
  373. On macOS the native binary is the recommended path when you do not need
  374. Docker, either through the [menu bar app](#macos-menu-bar-app) above or a
  375. [release tarball / launchd agent](docs/macos.md). Later updates for that
  376. path use `ai-memory upgrade` (checksum-verified GitHub release replace + hook
  377. refresh); see
  378. [`docs/install.md#keeping-ai-memory-up-to-date`](docs/install.md#keeping-ai-memory-up-to-date).
  379. The same native upgrade path covers Windows x86_64 zip installs under a
  380. writable prefix (see [`docs/windows.md`](docs/windows.md) Scenario C).
  381. Upgrading a 2.x install of any kind to 3.0? Read
  382. [`docs/upgrading-to-3.0.md`](docs/upgrading-to-3.0.md) first.
  383. Wiring another agent is the same two commands with a different name:
  384. `--client codex`, `--agent codex`, and so on for every row of the support
  385. matrix. OpenCode is version-detected by host-side commands; when generating its
  386. artifacts inside a container, use `setup-agent --agent opencode
  387. --opencode-dialect v1|v2 --to /tmp/unused` because the container cannot inspect
  388. the host executable. The legacy `opencode2`, `opencode-v2`, and `open-code2`
  389. aliases remain force-V2 compatibility spellings for old scripts; use
  390. `opencode` for new commands. The full per-agent guide, including Windows and
  391. remote servers, is [`docs/install.md`](docs/install.md).
  392. Two agents in the same project at once, or teammates on one server, work
  393. out of the box: the "current project" pointer is isolated per caller
  394. by default (v1.39+). See [`docs/auto-scope.md`](docs/auto-scope.md) for the
  395. optional session-aware Claude Code bridge and the details.
  396. **If in doubt, start your harness with `ai-memory run`.** It is the preferred
  397. way to launch: the first time it runs a harness it auto-installs that harness's
  398. ai-memory hooks + MCP if they are missing (so capture and recall work without
  399. a separate `install-hooks`/`install-mcp` step to forget), it wires the right
  400. project scope by construction, and it adds cross-harness *session* continuity on
  401. top of shared memory. Everything is idempotent and one-time per harness and
  402. config home. If the server is unreachable, `run` warns and launches anyway
  403. with local capture spooling; run `ai-memory recover` after the server returns
  404. (see [Degraded offline launches](docs/managed-workstreams.md#degraded-offline-launches)).
  405. Pass `--require-server` to fail closed instead.
  406. ```bash
  407. ai-memory run claude
  408. ai-memory run codex --yolo # same workstream + local Claude history dossier
  409. ai-memory run --profile work claude # reusable config.toml env/account preset
  410. ai-memory continue # resume the newest managed checkout
  411. # after a dead launcher left its lease behind (same operator only)
  412. ai-memory run --force-unlock codex
  413. ai-memory resume # pick a workstream; return to the picker after exit
  414. ai-memory resume --search auth # find a workstream by name (case-insensitive)
  415. ai-memory resume --all # pick across every linked checkout
  416. ```
  417. `--force-unlock` immediately expires the selected workstream's active lease;
  418. use it only when you know the previous launcher is gone. It does not kill a
  419. native process, and it cannot evict another authenticated operator's run. See
  420. the [managed-workstream recovery notes](docs/managed-workstreams.md#lease-recovery)
  421. for the full safety contract.
  422. On a real harness switch, the receiving managed agent is told to consult
  423. `AI_MEMORY_PREVIOUS_SESSION_HISTORY` when you ask to continue and the bounded
  424. portable packet lacks a detail. The variable names a private temporary
  425. Markdown projection created from the previous harness's checkout-validated,
  426. read-only adapter; the file disappears when the managed child exits. It is
  427. local to the launcher machine. This covers quota exhaustion and other abrupt
  428. exits where the old harness cannot write a handoff: refreshed ai-memory routing
  429. also tells the new agent that "continue", "resume", and "pick up where we left
  430. off" mean to read that file first when the three managed-run variables are
  431. present. A switch on another machine still gets the server's portable ledger
  432. and handoff, but cannot read a native transcript that exists only on the first
  433. machine.
  434. Without the managed launcher, a harness cut off the same way leaves no handoff
  435. at all, so the next one could pick up an older handoff or session page. When the
  436. newest captured work in the project is in another of your sessions that never
  437. ended and left no handoff after that work, the next session start carries a
  438. one-line notice that names that session. The agent then reads its newest prompts and
  439. tool results with `memory_read_session_observations`. The same session is
  440. listed first in `memory_briefing`'s `recent_sessions`, and `memory_handoff_list`
  441. names it as `newer_unended_session`.
  442. If that variable is absent on a real same-machine switch, run
  443. `type -a ai-memory` and `ai-memory --version` in the launching shell. This path
  444. requires the 3.1.0 or newer host client; a stale Cargo or package-manager binary
  445. earlier in `PATH` can shadow an updated wrapper.
  446. In `resume`, type to search, use Up/Down to select a workstream, and Left/Right
  447. to choose its harness. Enter launches the selection; Escape clears a search,
  448. then cancels when the search is empty (Ctrl-C always cancels).
  449. The list scrolls and loads every checkout-local page;
  450. there is no default workstream cutoff. Use `--limit N` only when you want to
  451. cap the matching results. Workstreams from other repositories or worktrees
  452. are left out unless you pass `--all`, which lists every linked checkout (the
  453. current one first); `continue` still resumes the newest linked checkout from
  454. anywhere. Listing reads Git identity only; it does not scan the working tree
  455. with `git status` before showing the picker. Full checkpoints are still captured
  456. when launching the selected workstream.
  457. Auto-wiring is on by default; opt out with `ai-memory run --no-autowire` or
  458. `AI_MEMORY_RUN_AUTOWIRE=false`. You can still wire agents by hand with
  459. `install-hooks` / `install-mcp` (e.g. for a harness you never launch through
  460. `ai-memory run`).
  461. `ai-memory uninstall --apply` removes everything ai-memory installed,
  462. and only what it installed. It also clears `ai-memory run`'s auto-wire
  463. record, so the next managed launch wires that harness again; to keep it
  464. unwired, launch with `--no-autowire` or set `AI_MEMORY_RUN_AUTOWIRE=false`. Install commands are idempotent and write
  465. timestamped backups next to any file they touch.
  466. ### NixOS
  467. This flake ships a NixOS module (`nixosModules.default`) with a
  468. `systemd.services.ai-memory` unit: a dedicated `ai-memory` system user
  469. (`nologin`, no linger) plus a hardened systemd sandbox
  470. (`ProtectSystem = "strict"`, empty capability sets,
  471. `MemoryDenyWriteExecute`, `RestrictAddressFamilies`, and the rest; see
  472. [`nix/systemd-sandbox.nix`](nix/systemd-sandbox.nix)). Packaged FHS units
  473. under `packaging/systemd/` keep their existing lighter hardening.
  474. The flake exports packages for `x86_64-linux`, `aarch64-linux`, and
  475. `aarch64-darwin`. Intel macOS remains supported by the release tarball and
  476. Homebrew, but not by the pinned Nixpkgs revision.
  477. ```nix
  478. {
  479. inputs.ai-memory.url = "github:akitaonrails/ai-memory";
  480. outputs = { nixpkgs, ai-memory, ... }: {
  481. nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
  482. system = "x86_64-linux";
  483. modules = [
  484. ai-memory.nixosModules.default
  485. {
  486. services.ai-memory = {
  487. enable = true;
  488. # enableWeb = true; # off by default — the web UI is opt-in
  489. # enableApi = true; # API-only companions; no browser UI
  490. settings = {
  491. allowed_hosts = [ "localhost" "127.0.0.1" "::1" "homelab.example" ];
  492. log_level = "info";
  493. };
  494. # Loopback (default): secrets optional; missing env file is tolerated.
  495. # Non-loopback: set one of ageSecret, sopsSecret, or environmentFile.
  496. # ageSecret = "ai-memory-env"; # config.age.secrets.<name> (agenix)
  497. # sopsSecret = "ai-memory/env"; # config.sops.secrets.<name> (sops-nix)
  498. };
  499. }
  500. ];
  501. };
  502. };
  503. }
  504. ```
  505. Declarative non-secret config lives in `services.ai-memory.settings` (a
  506. small typed set for common keys, plus `freeformType` for the rest of
  507. `config.toml`). The module renders a generated TOML file and passes
  508. `--config`. Top-level `bind`, `port`, and `enableWeb` win over duplicate
  509. settings keys. Anything in `settings` (including `llm_headers`) lands in a
  510. world-readable Nix store path, so do not put API keys there.
  511. Secrets such as `AI_MEMORY_AUTH_TOKEN` never go in `settings` or the
  512. world-readable Nix store. This includes `llm_headers`, which can carry API
  513. credentials; set `AI_MEMORY_LLM_HEADERS` in `ageSecret`, `sopsSecret`, or
  514. `environmentFile` instead. These three secret sources are mutually exclusive.
  515. Non-loopback binds require one; loopback may omit them and tolerates a missing
  516. environment file (systemd `EnvironmentFile=-…`). Put TLS in front of a LAN/WAN
  517. bind; see [`docs/https-via-proxy.md`](docs/https-via-proxy.md).
  518. All options and defaults are in [`nix/nixos-module.nix`](nix/nixos-module.nix).
  519. The module is entirely opt-in: `nix build`, `nix run`, `nix develop`, and the CLI are
  520. unchanged if you don't import it.
  521. `git` is a runtime dependency. Hook capture and `ai-memory doctor` run it to
  522. read the repository a session works in. The module puts `pkgs.git` on the
  523. service's `PATH`. The package itself leaves the binary unwrapped, because a
  524. wrapper renames the running process and the live-process guard in `reset`,
  525. `restore`, `reindex` and `uninstall --purge-data` looks for a process named
  526. `ai-memory`. If you install the package without the module (`nix profile
  527. install`, `home.packages`), install `git` next to it.
  528. ## Everyday use
  529. Day to day, you mostly do not think about ai-memory. Hooks capture
  530. prompts, tool calls, and session boundaries; session end turns them into
  531. readable wiki pages; the next session starts with a handoff.
  532. - Ask "where did we leave off?" to continue from the pending handoff.
  533. - Import a local PDF, DOCX, PPTX, XLSX, Markdown file, or VTT/SRT transcript as
  534. attributed, sanitized memory with the optional
  535. [`ai-memory-importer`](companions/ai-memory-importer) `document` command.
  536. - Ask "have we discussed X?" or "search memory for Y" to query the wiki.
  537. - Narrow a large wiki before ranking with `memory_query` filters such as
  538. `path_prefix: "procedures/"`, `tag: "rust"`, `kind: "decision"`, or
  539. `tier: "procedural"`.
  540. - Inspect content-free per-workload LLM call, outcome, latency, and usage
  541. telemetry with `ai-memory status --json`; it diagnoses the configured
  542. provider but does not route different workloads to different models.
  543. - Ask "catch me up" for a prose digest of recent project activity, or run
  544. `ai-memory recent` (`--global` for every project) to list the newest pages.
  545. - Search Chinese, Japanese and Korean text without spaces: zero-LLM search
  546. matches unspaced Han, Kana and Hangul substrings.
  547. - Run `ai-memory bootstrap` once when adopting an existing project with
  548. months of history.
  549. - Start the server with `--enable-web` for a read-only browser view of
  550. the wiki, a link graph at `/web/graph`, a root/operator managed-workstream
  551. overview at `/web/workstreams`,
  552. and a JSON API under `/api/v1`. On a server with a bearer token
  553. and no user accounts (every fresh install), the browser asks for a username
  554. and password: any username, and the contents of
  555. `<data_dir>/auth-tokens/default` as the password.
  556. - Investigate Claude Code and Codex response-token usage in the project
  557. dashboard, and pick a Light, Dark or System theme. See
  558. [Investigate token usage](docs/usage.md#investigate-token-usage-in-the-dashboard)
  559. for capture coverage, cache accounting and the investigation flags. You can
  560. drill down from a project to an agent, its sessions and individual responses.
  561. The updated Pi extension reports session totals only, not response-ledger rows.
  562. The web [agent inbox](docs/agent-messaging.md#in-the-web-ui) lets an operator
  563. queue requests for registered agents and read the received and sent history.
  564. Token filters run on the full authorized ledger, with native turn and tool
  565. context when reported. Pages show their sources, declared contradictions and
  566. recall explanations, and the [feature guide](docs/features.md) shows the
  567. effective installation states in the web UI.
  568. - Back up host-side harness configuration with
  569. `ai-memory backup-agents -o agent-assets.tar.gz`; inspect a restore with
  570. `ai-memory restore-agents -i agent-assets.tar.gz`, then add `--apply` only
  571. after reviewing the active skills, plugins, instructions, and destinations.
  572. Search modes, entities, feedback, briefings, and the web API are covered in [`docs/usage.md`](docs/usage.md) and
  573. [`docs/use-cases.md`](docs/use-cases.md).
  574. ### Interface language
  575. Use `ai-memory --language pt-BR status` or set `AI_MEMORY_LANGUAGE=pt-BR`
  576. for Brazilian Portuguese. The web interface follows the browser's language
  577. and offers an independent language selector. See [interface languages](docs/localization.md)
  578. for configuration, translation boundaries and contributor instructions.
  579. ## Teams and multiple machines
  580. Run the server somewhere reachable, such as a homelab box or a LAN host, and
  581. point every machine and every teammate at it. Knowledge is shared per
  582. project; personal handoffs stay personal; every write is attributed and
  583. audited. Multi-user auth (passwords, API credentials) is built in.
  584. Start with [`docs/users.md`](docs/users.md) for accounts and ownership,
  585. and [`docs/deploy.md`](docs/deploy.md) for the server itself. It includes
  586. measured capacity numbers and the one rule you must follow: one server per
  587. data directory, never two.
  588. Two opt-in HTTP surfaces build on the same browser sign-in, and both are off
  589. by default. `serve --enable-session-management` lets signed-in users inspect
  590. sessions and purge the ones they own
  591. ([`docs/session-management.md`](docs/session-management.md)).
  592. `serve --enable-self-service-keys` lets them issue and revoke their own `aim_`
  593. API keys ([`docs/self-service-keys.md`](docs/self-service-keys.md)).
  594. ## Security
  595. The server binds to loopback only by default. A fresh `ai-memory init` also
  596. mints a root bearer token into the data dir, which the hooks, the CLI and the
  597. `ai-memory mcp-bridge` stdio bridge read from there; it is never written into
  598. a harness config. An install created before that default (and the Docker
  599. quick-start) runs without auth until `ai-memory auth enable`, and
  600. `ai-memory status` says so. From there, hardening is incremental: a bearer
  601. token for the LAN, per-user accounts, OIDC device auth for hooks, TLS via
  602. a reverse proxy. Capture is sanitized at a typed privacy boundary before
  603. anything is stored, and per-repository `[capture]` rules can exclude
  604. paths or invert to allowlist mode. A repository can also route its capture
  605. to a different server than the one the hooks were installed against.
  606. Human login beyond loopback requires an HTTPS posture by default. Operators
  607. who explicitly accept plaintext passwords, cookies, credentials, and memory
  608. traffic on a private LAN can opt in with `serve --allow-insecure-human-auth`;
  609. the server never enables that exception implicitly.
  610. The full model is in [`docs/security.md`](docs/security.md),
  611. [`docs/users.md`](docs/users.md), and
  612. [`docs/https-via-proxy.md`](docs/https-via-proxy.md). For data-flow,
  613. identity/SSO, and offline-install questions specifically, see
  614. [`DATA_HANDLING.md`](DATA_HANDLING.md), [`docs/sso.md`](docs/sso.md), and
  615. [`docs/airgapped-install.md`](docs/airgapped-install.md).
  616. ## LLM providers
  617. Optional. Everything works with zero LLM calls; adding a provider
  618. upgrades session summaries and enables semantic search. Anthropic,
  619. OpenAI (including OAuth), Codex CLI credential reuse, GitHub Copilot, Gemini
  620. (through AI Studio or Vertex AI), OpenCode (Go and Zen), the Cursor Agent CLI (`cursor`), and
  621. any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported
  622. for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible
  623. endpoints for embeddings. Configuration lives in
  624. [`docs/llm-providers.md`](docs/llm-providers.md).
  625. For optional synthesized query answers, operators can set
  626. `[query_answer] max_context_tokens` to limit admitted evidence while retaining
  627. all retrieval hits. Known newer corrections take priority, and whole snippets
  628. are preferred over sentence-bounded fragments. It is disabled by default. See the
  629. [configuration reference](docs/ARCHITECTURE.md#configuration-configtoml) for the
  630. conservative counting rule and omission receipt.
  631. ## Architecture
  632. One Rust binary runs an MCP/HTTP server and owns one data directory:
  633. ```text
  634. <data_dir>/
  635. ├── wiki/ # markdown source of truth, git-versioned
  636. ├── raw/ # immutable sanitized managed-workstream transcript segments
  637. ├── db/ # SQLite indexes, including FTS5, entities, and embeddings
  638. ├── models/ # reserved for local embedding models
  639. └── logs/ # rolling tracing output
  640. ```
  641. Hooks POST observations to the server. The server serializes writes
  642. through one SQLite writer, compiles session observations into markdown
  643. pages, and serves retrieval through FTS5, entity-match and graph-neighbor RRF,
  644. optional vector RRF, an observation-evidence stream that lifts a session's
  645. page when its captured turns match (on by default), bounded source-authority
  646. adjustment, and bounded raw-observation fallback for non-global searches.
  647. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the data-flow
  648. diagram, crate breakdown, schema notes, and invariants.
  649. ## Docs
  650. ### For users
  651. | File | What it is |
  652. |---|---|
  653. | [`docs/testing-dashboard.md`](docs/testing-dashboard.md) | Dashboard behavior tests, real-browser CI and mutation probes that prove regression guards fail. |
  654. | [`docs/cookbook.md`](docs/cookbook.md) | **Task-oriented cheat sheet.** "I want to do X" → how: recall prior work, keep a project rule, import an existing knowledge base, get two agents/repos working together. Start here. |
  655. | [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine walkthrough. |
  656. | [`docs/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, slim routing snippet + managed Agent Skills, web UI, raw-wiki inspection, and the rules, memory and profile precedence. |
  657. | [`docs/cross-project-profile.md`](docs/cross-project-profile.md) | **The cross-project profile.** Your usual choices delivered to every project as defaults: defaults per deployment, every setting, per-project opt-outs, multi-user opt-in and privacy, CLI. |
  658. | [`docs/managed-workstreams.md`](docs/managed-workstreams.md) | Optional `ai-memory run` continuity across harnesses: auto harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. |
  659. | [`docs/agent-messaging.md`](docs/agent-messaging.md) | Cross-project agent-to-agent messaging: a directed, claim-once inbox/queue plus the on-start "you have mail" notice. |
  660. | [`docs/marker-file.md`](docs/marker-file.md) | Default repository-path project naming plus `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, worktrees, and work/personal separation, plus per-repository server profiles. |
  661. | [`docs/auto-scope.md`](docs/auto-scope.md) | `[auto_scope]` modes for shared servers: the default `per_actor` isolation, session-aware `per_session` isolation, and the pre-v1.39 `single` slot. |
  662. | [`docs/macos.md`](docs/macos.md) | macOS install paths: menu bar app, native release tarball, source build, Docker wrapper, launchd, and current limitations. |
  663. | [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and caveats. |
  664. | [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. |
  665. | [`docs/programmatic-memory.md`](docs/programmatic-memory.md) | Use ai-memory from any tool: MCP write/query/handoff calls, scope rules and incremental reads. |
  666. | [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, pointers to the TLS guide. |
  667. | [`docs/users.md`](docs/users.md) | **Multi-user attribution and human login.** Four-rung bearer ladder, password sessions, `ai-memory user` / `api-key` walkthrough, brownfield migration. |
  668. | [`docs/management-ui.md`](docs/management-ui.md) | Optional server-rendered console: feature gates, user and session management, MCP keys, public deployment, and frontend checks. |
  669. | [`docs/https-via-proxy.md`](docs/https-via-proxy.md) | **HTTPS via a reverse proxy.** When you need TLS and when you don't, with copy-paste Caddy / nginx / Cloudflare Tunnel templates and the "secure when you're not" failure modes. |
  670. | [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before purge / rename / merge / backup / restore / reset / reindex / restore-page.** Safety matrix, lossless project-identity merge, per-project disk layout, retained-version recovery, and operator workflows. |
  671. | [`docs/backup.md`](docs/backup.md) | Backing up the wiki + data dir to a remote git repository: what to include, what to exclude, scheduled push pattern, restore, and security posture. Companion to `docs/lifecycle-ops.md` (which covers the on-box `ai-memory backup` snapshot). |
  672. | [`docs/design-backup-agent-assets.md`](docs/design-backup-agent-assets.md) | Host agent-asset backup/restore: supported paths, filtering, redaction limits, archive bounds, active-content warning, and rollback behavior. |
  673. | [`docs/llm-providers.md`](docs/llm-providers.md) | Provider configuration for consolidation and embeddings. |
  674. | [`docs/security.md`](docs/security.md) | The full security model. |
  675. | [`docs/support-matrix.md`](docs/support-matrix.md) | The full agent/platform matrix with notes. |
  676. | [`docs/use-cases.md`](docs/use-cases.md) | Scenario walkthroughs. |
  677. | [`DATA_HANDLING.md`](DATA_HANDLING.md) | **Data-flow reference for security/legal review.** What's stored, what's local-only, the two opt-in external paths, and how deletion/retention work. |
  678. | [`docs/sso.md`](docs/sso.md) | Enterprise identity: the OIDC device-auth flow, its scope, and how to front the server with an OIDC-aware gateway. |
  679. | [`docs/airgapped-install.md`](docs/airgapped-install.md) | Offline/air-gapped install: self-contained build, checksum-verified release binaries, and offline local embedding models. |
  680. | [`docs/upgrading-to-3.0.md`](docs/upgrading-to-3.0.md) | Upgrading a 2.x install to 3.0: what changed, the removed token commands and their replacements, upgrade steps, and rollback. |
  681. | [`docs/MIGRATION-2.0.md`](docs/MIGRATION-2.0.md) | Upgrading an existing store to 2.0: the backup-gated automatic migration and how to restore. |
  682. | [`docs/benchmarks/`](docs/benchmarks/README.md) | Published retrieval-quality numbers with provenance, reproducible from the in-repo harness. |
  683. | [`docs/okf.md`](docs/okf.md) | The wiki is natively an Open Knowledge Format (OKF v0.2) bundle; design and field mapping. |
  684. ### For contributors
  685. | File | What it is |
  686. |---|---|
  687. | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
  688. | [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |
  689. | [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. |
  690. | [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), [team-wiki sync](companions/ai-memory-wikisync), the [TypeScript client SDK](companions/ai-memory-ts) and the [desktop installer](companions/ai-memory-desktop) (unsigned preview). |
  691. | [`docs/external-lifecycle.md`](docs/external-lifecycle.md) | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. |
  692. | [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |
  693. Dated `design-*`, `research-*`, `issues-*`, `desktop/`, and `benchmarks/`
  694. files are evidence and design records, not current operating instructions.
  695. Their status or snapshot banner says whether work shipped, remains proposed,
  696. or has been superseded. Use the user guides and `ARCHITECTURE.md` for current
  697. behavior; the older records remain only when current design rationale links to
  698. them.
  699. ### Community articles
  700. Written by users; not maintained here, so check them against the version you run.
  701. - [Installing and configuring ai-memory on Linux](https://www.linuxpro.com.br/2026/09/ai-memory-instalar-configurar-agentes-linux/) (pt-BR, LinuxPro, covers v2.6.3)
  702. - [ai-memory from v2.4 to v2.6.3](https://www.linuxpro.com.br/2026/10/ai-memory-a-evolucao-da-2-4-a-2-6-3/) (pt-BR, LinuxPro)
  703. The built-in web UI also has Documentation at `/web/docs` and a Changelog at
  704. `/web/docs/changelog`. The [feature activation guide](docs/features.md) covers
  705. prerequisites and verification. Agents can read the same bundled guides through
  706. authenticated `/api/v1/docs` JSON or each guide's Markdown link.
  707. ## License
  708. MIT. See [LICENSE](LICENSE).
  709. ## Acknowledgements
  710. This codebase is being built collaboratively with Claude Code
  711. (Anthropic Claude Opus 4.7) following the plan documented in
  712. `docs/design-decisions.md`.

Ratings and comments

Sign in to rate this skill.

Sign in

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