GitHub Trending Repositories

akitaonrails/ai-memory

Author: akitaonrails

Stars: 666 stars today

Description: Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

README

ai-memory

Long-term memory for AI coding agents. Quit Claude Code mid-task, start OpenAI Codex in the same directory, continue without re-explaining the architecture, the failed approaches, or the open questions.

Website: aimemory.sh

Website Release Rust License

Why ai-memory

Your coding agent probably has a memory feature already. Claude Code takes its own notes, Cursor remembers some things, and every platform is adding more. They all have the same limits: the notes live on one machine, belong to one agent, and drop out of view when you switch tools or hand the work to a teammate.

ai-memory removes those limits.

How it works

capture ──▶ consolidate ──▶ recall ──▶ handoff hooks session-end search next agent, observe summaries as + brief any harness silently wiki pages injection

Agents emit sanitized observations through lifecycle hooks as you work. At session end, observations become coherent markdown pages in the project's wiki (optionally LLM-written; useful even without). The next session, in any agent on any machine, gets a bounded brief and can search everything: full-text, entities, links, and (optionally) vectors, fused into one ranking. Cross-agent handoffs pass the baton explicitly.

The full design, including the invariants that keep multi-user and multi-session use safe, is in docs/ARCHITECTURE.md.

An optional server-rendered management console provides user administration, session inspection and deletion, and personal MCP API keys. Build with --features management-ui and start serve --transport http --enable-management-ui; both compile-time and runtime opt-ins are required.

Support matrix

Every row below is a first-party integration (MCP registration, lifecycle hooks, or both) checked by CI. The full matrix with per-agent notes and caveats is in docs/support-matrix.md.

| Area | Status | | --- | --- | | Linux | Supported | | NixOS module | Supported | | macOS | Supported | | Windows via WSL2 | Supported | | Native Windows | Experimental | | Claude Code | Supported | | Codex | Supported | | Command Code | Supported | | Devin CLI | Supported | | OpenCode (V1/V2 auto-detected) | Supported | | OpenCode V2 compatibility aliases (opencode2, opencode-v2, open-code2) | Supported | | Cursor | Supported | | Gemini CLI | Supported | | Oh My Pi / OMP | Supported | | Pi | Supported | | Crush | Managed-only | | Managed workstreams | Opt-in | | Claude Desktop | MCP-only | | OpenClaw | Supported | | Antigravity CLI | Supported | | Grok Build CLI | Supported | | Swival CLI | MCP-only | | Zero | Supported | | ZCode | Supported | | Kimi Code | Supported | | Kiro CLI | Supported | | Pool | Hooks-only | | GitHub Copilot CLI | Supported | | Factory Droid | Supported | | Meta Muse Code | Supported | | CodeBuddy Code | Hooks-only | | IBM Bob | Supported | | VS Code Copilot | MCP-only | | Zed | MCP-only | | DeepSeek Harness (DSH) | MCP-only | | Prime Agent | MCP-only | | Hermes Agent | Supported | | GrizzyBot | Supported | | LLM/auth providers | Supported | | Embedding providers | Supported |

Coming from another tool?

Most agent-memory tools optimize for one thing: extracting atomic facts per turn, a temporal knowledge graph, an agent-editable memory OS, or a hosted context API. ai-memory is built around a git-backed markdown wiki as the source of truth, with a derived index for retrieval. It captures automatically from lifecycle hooks, is shared across agents, machines, and people, and works with zero LLM calls by default. This table shows what carries over from each tool and what you gain:

| Coming from… | What's similar | What you gain | |---|---|---| | 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 | | 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 | | 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 | | 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 | | 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 | | 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) | | 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 |

Across all of these, ai-memory gives you files you own (git-backed markdown), a zero-LLM default, one self-contained binary, sharing across agents, machines, and teams, automatic lifecycle capture, and typed, claim-once handoffs. Opt-in features (LLM consolidation, vector search, the "dream" consolidation pass, belief-strength in ranking) stay opt-in, and the zero-LLM aging path (per-tier decay, extractive compaction, dedup, contradiction flagging, access-weighted retention) works with no API key at all.

Built on the shoulders of: the Karpathy LLM Wiki (compile-not-retrieve), agentmemory (hook capture for coding agents), basic-memory (markdown-on-disk truth), cognee (pipeline composition and triplet embeddings), Hermes Agent (the self-improvement loop), and A-MEM (Zettelkasten-style atomic notes).

The full comparison, covering where each approach wins, where ai-memory differs, and the published benchmark, is in How ai-memory compares.

Quick start

Linux and macOS (two commands, no root)

bash 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. An AI agent installing ai-memory for you can follow 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):

bash 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.

Windows (two commands, no admin)

In PowerShell:

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.

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.

bash 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

Fedora (RPM)

Download the x86_64 or aarch64 RPM from the latest release, then install it:

bash 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.

bash ai-memory setup

System service installs use /var/lib/ai-memory and /etc/ai-memory/ via the packaged unit. Full user-service, system-service, auth, and provider setup is in docs/install.md#arch-linux-native-packages-aur.

macOS (menu bar app)

A self-contained .app that bundles the native ai-memory binary and hooks/ tree, starts the existing LaunchAgent, and opens /web, ai-memory status, and config.toml from the menu bar. Wiki, SQLite, config, and models stay in ~/Library/Application Support/ai-memory, so replacing the app is an update and does not rewrite that tree.

Needs a Rust toolchain and Xcode / Swift 6 (same as a source build):

bash git clone https://github.com/akitaonrails/ai-memory cd ai-memory ./companions/ai-memory-macos/build.sh open "companions/ai-memory-macos/dist/AI Memory.app"

Drag AI Memory.app to /Applications, then Install & Start Server from the menu extra (no Dock icon). The app reads the bearer token init wrote into its data dir, so the status item turns green on its own. Then wire your agents with the bundled binary; --no-service leaves the app's LaunchAgent in charge:

bash BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory" "$BIN" setup --no-service

Prebuilt tarball and launchd-without-the-app paths: docs/macos.md. Companion details: companions/ai-memory-macos.

Docker

You need: Docker or Podman + an agent CLI from the Support Matrix, or anything else that speaks MCP.

The published Docker image includes linux/amd64 and linux/arm64 variants, so Apple Silicon Macs and ARM64 Linux hosts can pull akitaonrails/ai-memory without --platform linux/amd64 emulation.

The Docker quick-start below has no authentication: the container never runs init, so it starts without a token. The server binds to loopback only, so nothing outside the machine can reach it, but local processes and browser pages can. Native installs that run ai-memory init get a bearer token by default; see Security below for that and for adding a token here.

```bash

1. Install the ai-memory CLI wrapper (a small shell script that

runs the binary inside a container with your $HOME mounted). This is

the only thing that needs to live on the host filesystem.

mkdir -p ~/.local/bin wrapper_tmp="$(mktemp -d)" trap 'rm -rf "$wrapper_tmp"' EXIT wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper" curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256" expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")" if command -v sha256sum >/dev/null 2>&1; then actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')" else actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')" fi [ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; } install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory rm -rf "$wrapper_tmp" trap - EXIT

Most distros put ~/.local/bin on PATH automatically. If `which

ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

2. Start the server. --restart unless-stopped makes it come back

on docker daemon restart and on machine boot (provided your

docker service is enabled at boot — `sudo systemctl enable

dockeron most distros). Loopback-only bind (127.0.0.1:49374`)

so nothing outside this machine can reach it. Omit the LLM /

EMBEDDING lines for zero-LLM mode — FTS5 search still works

without any keys.

docker run -d --name ai-memory \ --restart unless-stopped \ -p 127.0.0.1:49374:49374 \ -v ai-memory-data:/data \ -e AI_MEMORY_LLM_PROVIDER=anthropic \ -e ANTHROPIC_API_KEY=sk-ant-... \ -e AI_MEMORY_EMBEDDING_PROVIDER=openai \ -e OPENAI_API_KEY=sk-... \ docker.io/akitaonrails/ai-memory:latest

3. Wire your agent CLI in two commands. The wrapper takes care of

mounts and each client's config-path detection. Re-run with

--agent codex, --agent command-code, --agent devin, --agent opencode, --agent opencode2, --agent gemini-cli,

--agent grok, --agent kimi-code, --agent kiro-cli, --agent copilot-cli, --agent droid, --agent muse, --agent omp,

--agent oh-my-pi, --client cursor,

--client gemini-cli, --client grok, --client kiro-cli, etc.

for additional agents; full list in docs/install.md.

ai-memory install-mcp --client claude-code --apply ai-memory install-hooks --agent claude-code --apply ```

On Linux and macOS, the Docker wrapper runs install-hooks through its checksum-verified native host client. The installed hooks therefore enforce client-side capture controls such as [capture] ignore_paths and allowlist mode before an event reaches the spool or network. Set AI_MEMORY_HOOK_PLATFORM=posix explicitly only when you need the legacy shell compatibility path; the installer warns that path cannot enforce capture policy v1.

The examples use docker; replace it with podman on a Podman host. The wrapper automatically uses Podman when Docker is not installed. Set AI_MEMORY_DOCKER=podman to force Podman when both engines are available.

That completes the setup on Linux/macOS. Start a Claude Code session as usual: every prompt and tool call now lands in ai-memory, and the next session you open in this project will see a handoff with where you left off. On macOS the native binary is the recommended path when you do not need Docker, either through the menu bar app above or a release tarball / launchd agent. Later updates for that path use ai-memory upgrade (checksum-verified GitHub release replace + hook refresh); see docs/install.md#keeping-ai-memory-up-to-date. The same native upgrade path covers Windows x86_64 zip installs under a writable prefix (see docs/windows.md Scenario C). Upgrading a 2.x install of any kind to 3.0? Read docs/upgrading-to-3.0.md first.

Wiring another agent is the same two commands with a different name: --client codex, --agent codex, and so on for every row of the support matrix. OpenCode is version-detected by host-side commands; when generating its artifacts inside a container, use setup-agent --agent opencode --opencode-dialect v1|v2 --to /tmp/unused because the container cannot inspect the host executable. The opencode2 aliases remain force-V2 compatibility spellings. The full per-agent guide, including Windows and remote servers, is docs/install.md.

Two agents in the same project at once, or teammates on one server, work out of the box: the "current project" pointer is isolated per caller by default (v1.39+). See docs/auto-scope.md for the optional session-aware Claude Code bridge and the details.

If in doubt, start your harness with ai-memory run. It is the preferred way to launch: the first time it runs a harness it auto-installs that harness's ai-memory hooks + MCP if they are missing (so capture and recall work without a separate install-hooks/install-mcp step to forget), it wires the right project scope by construction, and it adds cross-harness session continuity on top of shared memory. Everything is idempotent and one-time per harness and config home. If the server is unreachable, run warns and launches anyway with local capture spooling; run ai-memory recover after the server returns (see Degraded offline launches). Pass --require-server to fail closed instead.

```bash ai-memory run claude ai-memory run codex --yolo # same workstream + local Claude history dossier ai-memory run --profile work claude # reusable config.toml env/account preset ai-memory continue # resume the newest managed checkout

after a dead launcher left its lease behind (same operator only)

ai-memory run --force-unlock codex ai-memory resume # pick from ALL workstreams in this checkout only ai-memory resume --search auth # find a workstream by name (case-insensitive) ai-memory resume --all # pick across every linked checkout ```

--force-unlock immediately expires the selected workstream's active lease; use it only when you know the previous launcher is gone. It does not kill a native process, and it cannot evict another authenticated operator's run. See the managed-workstream recovery notes for the full safety contract.

On a real harness switch, the receiving managed agent is told to consult AI_MEMORY_PREVIOUS_SESSION_HISTORY when you ask to continue and the bounded portable packet lacks a detail. The variable names a private temporary Markdown projection created from the previous harness's checkout-validated, read-only adapter; the file disappears when the managed child exits. It is local to the launcher machine. This covers quota exhaustion and other abrupt exits where the old harness cannot write a handoff: refreshed ai-memory routing also tells the new agent that "continue", "resume", and "pick up where we left off" mean to read that file first when the three managed-run variables are present. A switch on another machine still gets the server's portable ledger and handoff, but cannot read a native transcript that exists only on the first machine.

If that variable is absent on a real same-machine switch, run type -a ai-memory and ai-memory --version in the launching shell. This path requires the 3.1.0 or newer host client; a stale Cargo or package-manager binary earlier in PATH can shadow an updated wrapper.

In resume, type to search, use Up/Down to select a workstream, and Left/Right to choose its harness. Enter launches the selection; Escape clears a search, then cancels when the search is empty (Ctrl-C always cancels). The list scrolls and loads every checkout-local page; there is no default workstream cutoff. Use --limit N only when you want to cap the matching results. Workstreams from other repositories or worktrees are left out unless you pass --all, which lists every linked checkout (the current one first); continue still resumes the newest linked checkout from anywhere. Listing reads Git identity only; it does not scan the working tree with git status before showing the picker. Full checkpoints are still captured when launching the selected workstream.

Auto-wiring is on by default; opt out with ai-memory run --no-autowire or AI_MEMORY_RUN_AUTOWIRE=false. You can still wire agents by hand with install-hooks / install-mcp (e.g. for a harness you never launch through ai-memory run).

ai-memory uninstall --apply removes everything ai-memory installed, and only what it installed. It also clears ai-memory run's auto-wire record, so the next managed launch wires that harness again; to keep it unwired, launch with --no-autowire or set AI_MEMORY_RUN_AUTOWIRE=false. Install commands are idempotent and write timestamped backups next to any file they touch.

NixOS

This flake ships a NixOS module (nixosModules.default) with a systemd.services.ai-memory unit: a dedicated ai-memory system user (nologin, no linger) plus a hardened systemd sandbox (ProtectSystem = "strict", empty capability sets, MemoryDenyWriteExecute, RestrictAddressFamilies, and the rest; see nix/systemd-sandbox.nix). Packaged FHS units under packaging/systemd/ keep their existing lighter hardening. The flake exports packages for x86_64-linux, aarch64-linux, and aarch64-darwin. Intel macOS remains supported by the release tarball and Homebrew, but not by the pinned Nixpkgs revision.

```nix { inputs.ai-memory.url = "github:akitaonrails/ai-memory";

outputs = { nixpkgs, ai-memory, ... }: { nixosConfigurations.myhost = nixpkgs.lib.nixosSystem { system = "x86_64-linux"; modules = [ ai-memory.nixosModules.default { services.ai-memory = { enable = true; # enableWeb = true; # off by default — the web UI is opt-in # enableApi = true; # API-only companions; no browser UI settings = { allowed_hosts = [ "localhost" "127.0.0.1" "::1" "homelab.example" ]; log_level = "info"; }; # Loopback (default): secrets optional; missing env file is tolerated. # Non-loopback: set one of ageSecret, sopsSecret, or environmentFile. # ageSecret = "ai-memory-env"; # config.age.secrets. (agenix) # sopsSecret = "ai-memory/env"; # config.sops.secrets. (sops-nix) }; } ]; }; }; } ```

Declarative non-secret config lives in services.ai-memory.settings (a small typed set for common keys, plus freeformType for the rest of config.toml). The module renders a generated TOML file and passes --config. Top-level bind, port, and enableWeb win over duplicate settings keys. Anything in settings (including llm_headers) lands in a world-readable Nix store path, so do not put API keys there.

Secrets such as AI_MEMORY_AUTH_TOKEN never go in settings or the world-readable Nix store. This includes llm_headers, which can carry API credentials; set AI_MEMORY_LLM_HEADERS in ageSecret, sopsSecret, or environmentFile instead. These three secret sources are mutually exclusive. Non-loopback binds require one; loopback may omit them and tolerates a missing environment file (systemd EnvironmentFile=-…). Put TLS in front of a LAN/WAN bind; see docs/https-via-proxy.md.

All options and defaults are in nix/nixos-module.nix. The module is entirely opt-in: nix build, nix run, nix develop, and the CLI are unchanged if you don't import it.

git is a runtime dependency. Hook capture and ai-memory doctor run it to read the repository a session works in. The module puts pkgs.git on the service's PATH. The package itself leaves the binary unwrapped, because a wrapper renames the running process and the live-process guard in reset, restore, reindex and uninstall --purge-data looks for a process named ai-memory. If you install the package without the module (nix profile install, home.packages), install git next to it.

Everyday use

Day to day, you mostly do not think about ai-memory. Hooks capture prompts, tool calls, and session boundaries; session end turns them into readable wiki pages; the next session starts with a handoff.

Search modes, entities, feedback, briefings, and the web API are covered in docs/usage.md and docs/use-cases.md.

Teams and multiple machines

Run the server somewhere reachable, such as a homelab box or a LAN host, and point every machine and every teammate at it. Knowledge is shared per project; personal handoffs stay personal; every write is attributed and audited. Multi-user auth (passwords, API credentials) is built in.

Start with docs/users.md for accounts and ownership, and docs/deploy.md for the server itself. It includes measured capacity numbers and the one rule you must follow: one server per data directory, never two.

Two opt-in HTTP surfaces build on the same browser sign-in, and both are off by default. serve --enable-session-management lets signed-in users inspect sessions and purge the ones they own (docs/session-management.md). serve --enable-self-service-keys lets them issue and revoke their own aim_ API keys (docs/self-service-keys.md).

Security

The server binds to loopback only by default. A fresh ai-memory init also mints a root bearer token into the data dir, which the hooks, the CLI and the ai-memory mcp-bridge stdio bridge read from there; it is never written into a harness config. An install created before that default (and the Docker quick-start) runs without auth until ai-memory auth enable, and ai-memory status says so. From there, hardening is incremental: a bearer token for the LAN, per-user accounts, OIDC device auth for hooks, TLS via a reverse proxy. Capture is sanitized at a typed privacy boundary before anything is stored, and per-repository [capture] rules can exclude paths or invert to allowlist mode. A repository can also route its capture to a different server than the one the hooks were installed against.

The full model is in docs/security.md, docs/users.md, and docs/https-via-proxy.md. For data-flow, identity/SSO, and offline-install questions specifically, see DATA_HANDLING.md, docs/sso.md, and docs/airgapped-install.md.

LLM providers

Optional. Everything works with zero LLM calls; adding a provider upgrades session summaries and enables semantic search. Anthropic, OpenAI (including OAuth), Codex CLI credential reuse, GitHub Copilot, Gemini, OpenCode (Go and Zen), the Cursor Agent CLI (cursor), and any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible endpoints for embeddings. Configuration lives in docs/llm-providers.md.

Architecture

One Rust binary runs an MCP/HTTP server and owns one data directory:

text <data_dir>/ ├── wiki/ # markdown source of truth, git-versioned ├── raw/ # immutable sanitized managed-workstream transcript segments ├── db/ # SQLite indexes, including FTS5, entities, and embeddings ├── models/ # reserved for local embedding models └── logs/ # rolling tracing output

Hooks POST observations to the server. The server serializes writes through one SQLite writer, compiles session observations into markdown pages, and serves retrieval through FTS5, entity-match and graph-neighbor RRF, optional vector RRF, an observation-evidence stream that lifts a session's page when its captured turns match (on by default), bounded source-authority adjustment, and bounded raw-observation fallback for non-global searches.

See docs/ARCHITECTURE.md for the data-flow diagram, crate breakdown, schema notes, and invariants.

Docs

For users

| File | What it is | |---|---| | 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. | | 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. | | 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. | | 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. | | docs/managed-workstreams.md | Optional ai-memory run continuity across harnesses: auto harness selection, native resume, argument forwarding, ledger search, privacy, and recovery. | | docs/agent-messaging.md | Cross-project agent-to-agent messaging: a directed, claim-once inbox/queue plus the on-start "you have mail" notice. | | 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. | | 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. | | docs/macos.md | macOS install paths: menu bar app, native release tarball, source build, Docker wrapper, launchd, and current limitations. | | docs/windows.md | Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and caveats. | | docs/mcp-install.md | Per-client MCP and lifecycle notes, handoff-injection limits, and community bridge guidance. | | docs/programmatic-memory.md | Use ai-memory from any tool: MCP write/query/handoff calls, scope rules and incremental reads. | | docs/deploy.md | Homelab deploy: bin/deploy, bearer-token auth, pointers to the TLS guide. | | docs/users.md | Multi-user attribution and human login. Four-rung bearer ladder, password sessions, ai-memory user / api-key walkthrough, brownfield migration. | | docs/management-ui.md | Optional server-rendered console: feature gates, user and session management, MCP keys, public deployment, and frontend checks. | | 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. | | docs/lifecycle-ops.md | Read before purge / rename / backup / restore / reset / reindex / restore-page. Safety matrix, per-project disk layout, checkpoint page recovery, and operator workflows. | | 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). | | docs/design-backup-agent-assets.md | Host agent-asset backup/restore: supported paths, filtering, redaction limits, archive bounds, active-content warning, and rollback behavior. | | docs/llm-providers.md | Provider configuration for consolidation and embeddings. | | docs/security.md | The full security model. | | docs/support-matrix.md | The full agent/platform matrix with notes. | | docs/use-cases.md | Scenario walkthroughs. | | 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. | | docs/sso.md | Enterprise identity: the OIDC device-auth flow, its scope, and how to front the server with an OIDC-aware gateway. | | docs/airgapped-install.md | Offline/air-gapped install: self-contained build, checksum-verified release binaries, and offline local embedding models. | | 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. | | docs/MIGRATION-2.0.md | Upgrading an existing store to 2.0: the backup-gated automatic migration and how to restore. | | docs/benchmarks/ | Published retrieval-quality numbers with provenance, reproducible from the in-repo harness. | | docs/okf.md | The wiki is natively an Open Knowledge Format (OKF v0.2) bundle; design and field mapping. |

For contributors

| File | What it is | |---|---| | docs/ARCHITECTURE.md | Operational summary: data flow, crate layout, cross-cutting invariants, schema. | | docs/design-decisions.md | The full v1 spec. | | docs/managed-harness-contributions.md | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. | | docs/companion-crates.md | Optional companion projects: the importer, external lifecycle relay, team-wiki sync, the TypeScript client SDK and the desktop installer (unsigned preview). | | docs/external-lifecycle.md | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. | | docs/auto-improvement-loop.md | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |

Community articles

Written by users; not maintained here, so check them against the version you run.

License

MIT. See LICENSE.

Acknowledgements

This codebase is being built collaboratively with Claude Code (Anthropic Claude Opus 4.7) following the plan documented in docs/design-decisions.md.

File Structure

Unable to fetch file structure.

Back to Trending