Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
Changelog: 0.x releases (archived)
The 0.x release notes, moved out of the root CHANGELOG.md when the
next major line began. They are frozen like every released section.
0.16.0 - 2026-06-11
Added
- Native Claude Code hooks on macOS/Linux now use the direct
ai-memory hook --event ...command by default, matching native Windows. Native hook commands spool events locally and can authenticate with a stored per-developer OIDC device token instead of a shared static hook token. ai-memory auth login oidc-device --issuer <url> --client-id <id>stores a generic OIDC device-flow token for native hook authentication.
Fixed
ai-memory uninstall --only hooksnow recognizes and removes nativeai-memory hook ...commands as well as legacy script commands.
0.15.0 - 2026-06-11
Added
- Wiki recovery checkpoints now have first-class operator commands:
ai-memory checkpointslists recent wiki git commits andai-memory restore-page --path <page.md> --from <rev>restores one page from a checkpoint, writes a new post-restore checkpoint, and reindexes the restored page into SQLite. Startup also creates a one-time upgrade baseline checkpoint for existing wiki trees that had no git commits yet.
Fixed
- Release publication now limits the GitHub Release asset download step to
ai-memory-*artifacts, avoiding Docker Buildx side artifacts that can make tag workflows fail after binaries and Docker images are already published.
0.14.0 - 2026-06-11
Added
- Tagged releases now publish a native Windows x86_64 zip artifact
(
ai-memory-windows-x86_64.zip) withai-memory.exe, hooks, default config template, checksums, and Windows install docs, giving native Windows agents a no-toolchain path to the fast direct-binary hook mode.
0.13.0 - 2026-06-08
Added
- New
ai-memory reindexlifecycle command rebuilds the derived SQLite page index from the on-disk wiki. It recreates workspace/project rows from per-scope_meta.mdmanifests while preserving the UUIDs encoded in the wiki tree, then reindexes page markdown into pages, links, and FTS. The command refuses to run unless the SQLite store is clean; operators should stop the server, back up data, move/removedb/memory.sqlite, runreindex, and recompute embeddings separately withembedwhen needed. - Wiki startup now backfills per-workspace and per-project
_meta.mdmanifests containing the human workspace/project names (andrepo_pathfor projects) so the markdown tree is self-describing enough to rebuild the derived DB.
Fixed
- Wiki reindexing now treats
log.md/log-YYYY-MM.mdas raw hook ledgers only when their content opens with the hook log prefix, so ordinary markdown pages with reserved-looking names are no longer silently dropped._meta.mdmanifests and direct watcher events also reject symlinks before reading.
0.12.3 - 2026-06-07
0.12.2 - 2026-06-07
Fixed
- The hook router no longer auto-creates fragment "projects" for
subdirectory cwds. When a tool call's cwd sits inside an existing
project's
repo_pathtree (for example aReadofmanga-plus/reader/src/main.rswhile the session is attributed tomanga-plus), the resolver now picks the existing parent project instead of materialising asrcorreaderproject for the subdirectory name. The schema columnprojects.repo_pathhas always been there for exactly this kind of cwd matching; the resolver finally queries it. Sub-projects declared via.ai-memory.tomlstill win because their longerrepo_pathranks ahead. Newfind_project_by_cwd_prefixreader helper covers the query. Three regression tests inai-memory-hooks::router::testspin the parent / sub-project / cold-start paths. - V19 data-repair migration re-attributes pre-existing orphan
observations and handoffs to their session's project, then deletes
the now-truly-empty fragment project rows that were left behind
by the bug above. The session is the source of truth — observations
belong to the session that emitted them and the FK enforces
session existence. The migration is idempotent (re-running on a
repaired DB is a no-op) and runs once per data directory at server
startup via the existing refinery chain.
scratchis explicitly preserved per CLAUDE.md invariant #15a (defensive cwd-less default).
0.12.1 - 2026-06-07
Fixed
GET /favicon.iconow lives at the absolute host root, outside--base-pathand outside the/webnest, so the browser's automatic favicon fetch actually reaches it. The 0.12.0 build mounted the route inside the web router and ended up serving the icon only at/web/favicon.ico— invisible to the browser's auto-fetch (the icon still appeared via the in-page<link rel="icon">tag, so the user-visible behaviour stayed correct, but the dedicated route was unreachable). The new mount is also exempt from bearer auth and the host allowlist so a fresh tab gets the icon without an HTTP Basic prompt; the embedded PNG is the same one any visitor to/webalready sees, so the info-leak surface is nil. Surfaced by the post-merge audit live test ([#79]).
0.12.0 - 2026-06-07
Added
- New
ai-memory hooksubcommand emits one lifecycle event natively (reads the JSON payload from stdin, POSTs to/hook, GETs/handoffonsession-start) without spawning a shell. On native Windows, Claude Code now defaults to the native hook command — measured3.5-5× faster per tool-call hook (735 ms shell → ~150-205 ms native on an i7-6700HQ). Opt back into the previous Git Bash +.shpath withAI_MEMORY_HOOK_PLATFORM=windows-bash. Seedocs/windows.md([#84]). - New
GET /favicon.icoroute on the web UI serves the same logo bytes as the header, so the browser tab carries an icon without an extra asset embed ([#79]). - Thin-client CLI commands (
status,write-page,search,read-page,embed,lint,backup, …) now respect the server's base-path mount viaAI_MEMORY_BASE_PATHor the path component ofAI_MEMORY_SERVER_URL(URL path wins), so deployments hosted behind a reverse proxy under a subpath stop 404'ing — including the containerHEALTHCHECK(ai-memory status). Empty / unset means root mount, byte-identical to the prior behaviour ([#82]).
Changed
- The embedded web UI ships a single transparent 768×768 PNG (~126 KB,
down from a 992 KB JPEG mislabelled as PNG) used for both the header
logo and the favicon. README branding stays on the existing
light/dark pair via
<picture>([#79]).
Fixed
install-hooks --apply(andai-memory upgrade, which calls it) now MERGES into per-event hook arrays instead of replacing them, so third-party hooks registered under the same event (e.g. a context-modeSessionStartguard) survive re-apply. ai-memory-owned entries are still swapped for the fresh ones; re-runs stay idempotent. Resolves #80 ([#83]).- FTS5 searches for filenames carrying ASCII punctuation no longer error
or silently miss.
current.md(which used to surfacefts5: syntax error near ".") andui-refresh(which silently returned zero hits despitefollow-ups/ui-refresh-scroll-restoration.mdexisting) both work end-to-end. Punctuated tokens are now quoted as both whole-form and split-form phrases, OR'd, to satisfy the asymmetry between the content tokenizer (tokenchars '/_-'keeps them inside tokens) and the path index (which pre-expands/_-.to spaces) ([#81]).
0.11.0 - 2026-06-05
Added
- New
[auto_scope]config block (mode,session_ttl_secs,max_entries) selects how the hook-published "currently active project" pointer is shared across concurrent MCP callers. The defaultsinglemode preserves the historical process-wide slot. Opt-inper_sessionkeys the pointer bysession_idto isolate concurrent agent runs of the same operator; opt-inper_actorkeys by(user, session_id)to isolate across operators as well, pairing with multi-user mode whereusercomes from theusersrow that owns the bearer token.per_actoralso keeps a user-only fallback slot so authenticated MCP requests from clients that cannot forward a session id do not inherit another user's latest project; same-user session isolation still requires a client/bridge that sendsX-Memory-Actor-Session-IdorMcp-Session-Idon MCP tool calls. Per-key entries carry an insertion timestamp and are TTL-evicted (default 1 hour) and capped (default 4096) so adversarial / runaway clients cannot grow the map without bound. Both opt-in modes still publish to the single slot in parallel, so any caller without actor context falls back gracefully to the most recent project rather than an empty pointer. All MCP read tools (memory_query,memory_recent,memory_read_page,memory_status,memory_briefing,memory_explore,memory_lint,memory_forget_sweep,memory_handoff_*) now thread the request'sActorContextinto scope resolution, so opt-in isolation takes effect for the full read surface.
Fixed
- Claude Code lifecycle hooks now emit structured JSON on stdout. Fire-and-
forget hooks return
{}, andSessionStartwraps pending handoff text inhookSpecificOutput.additionalContext, avoiding Claude Code's repeated "Hook output does not start with {" debug spam while preserving handoff injection. POST /admin/rename-projectnow returns404 Not Foundwhen the project row has been deleted (typically by a concurrentpurge-project) between the handler's id lookup and the writer'sUPDATE. The pre-fix path silently responded200 OKwithpages: 0for an operation that affected zero rows, which contradicted the concurrent purge's also-200 OKdestruction of the same project and gave operators no signal that the rename had been undone.
0.10.0 - 2026-06-04
Added
- New
POST /admin/delete-pageHTTP endpoint deletes a single page with explicit(workspace, project). Likepurge-project/rename-project, it uses no-create lookup — a delete on a typo'd or wrong scope now returns404 workspace 'X' not foundinstead of silently auto-creating the container and returning misleadingdeleted: true. - New
ai-memory delete-page --path <P> --workspace <W> --project <P>CLI subcommand, a thin client of/admin/delete-page. Mirrors the write-page/read-page CLI shape so terminal users get a complete delete-single-page surface for the first time. - New
memory_handoff_cancelMCP tool marks an exact open handoff id expired, giving agents a safe way to discard a mistakenly-created pending handoff before the next session consumes stale context.
Fixed
- MCP tool descriptions and routing snippets now draw a sharper boundary
between read-only
memory_briefingand session-endingmemory_handoff_begin, reducing accidental dangling handoffs when an agent was only asked for project status. - Custom
--web-ui-dirSPAs mounted at a non-root--web-slugnow serve the injected shell at the trailing-slash root too (for example/web/), matching/weband deep client routes instead of returning a refresh-only 404. - OpenCode and OMP generated hooks now derive
project_strategy = "repo-root"project names from the host-visible.ai-memory.tomlmarker directory before sending hook payloads, so dockerized servers no longer fall back to git discovery inside paths they cannot see. memory_delete_page(MCP) now acceptsworkspacealongsideprojectand routes scope througheffective_ids_for_read_args, the same path the read tools use. Previously a project name that lived in multiple workspaces could silently route the delete to the wrong slot and returndeleted: truefor a page that was never touched. Operators on shared (multi- workspace) servers should explicitly passworkspace + projectto make the target unambiguous.
0.9.0 - 2026-06-02
Added
openai-compatLLM providers can now opt into strict JSON Schema structured output withAI_MEMORY_LLM_COMPAT_STRICT=true. Strict mode sendsresponse_format=json_schemafirst for compatible Ollama, vLLM, LM Studio, llama.cpp, and gateway endpoints, while the tolerant JSON-object parser remains the default and the fallback for strict raw-call failures ([#70]).- The read-only web browser now renders
[[wiki links]]as clickable internal links to the target page. Supports[[path]],[[path|label]],[[project:path]], and[[workspace/project:path]], resolved against the current page's project unless the target carries its own scope; bare targets get a.mdsuffix. External schemes, path traversal, and links inside fenced or inline code are left as literal text ([#68]). ai-memory serve --transport httpcan host the entire HTTP surface under a configurable subpath with--base-path/AI_MEMORY_BASE_PATH;/mcp,/hook,/admin/*,/api/v1, and the web UI all move under that prefix. The web UI mount can also be changed with--web-slug, and custom--web-ui-dirSPAs receive injected<base href>plusai-memory-base-pathmetadata for same-origin API calls behind reverse proxies ([#65]).ai-memory move-projectcan move projects across workspaces via the admin API. Fresh destinations use a lossless true move that keeps the sameproject_id, sessions, observations, handoffs, embeddings, and page history; existing same-named destination projects use copy-purge merge with expliciton_conflicthandling. Admission webhooks can subscribe to the newmove_projectevent and receive destination names in the context ([#60]).- Page FTS now indexes normalized page paths, so searches can find pages by filename or slug even when the slug does not appear in the title/body ([#62]).
- Admission webhooks can now observe, mutate, or reject engine write/delete/ purge operations, with authenticated actor context, loop-prevention skip lists for trusted re-entry, and non-blocking observer webhooks for mirrors and backups ([#55]).
- New
memory_delete_pageMCP tool deletes a single page by exact path, updates the SQLite index directly, and firesop=deleteadmission hooks before removal ([#55]).
Fixed
- Backups no longer dereference symlinks under
wiki/, preventing a planted wiki symlink from pulling arbitrary readable host-file contents intobackup.tar.gz. ai-memory restorenow validates tar entries before extraction and accepts only regular files/directories under the expected backup paths (wiki/,db/memory.sqlite, andconfig.toml), rejecting links, special files, unsafe paths, and unexpected archive entries.- In multi-user mode (
[auth].token_pepperconfigured), operational/admin/*endpoints now require the root token; DB-user tokens receive 403 while single-user installs keep the historical permissive admin behavior. - LLM provider clients now cap provider response bodies before JSON, text, or SSE parsing, and truncate error bodies from bounded buffers instead of buffering arbitrary-size responses.
- Non-blocking admission webhooks now have a process-level in-flight cap and webhook timeouts are clamped to a safe maximum, preventing observer hooks from growing unbounded background work during write bursts.
- Hook cwd/project resolution caching is now bounded with LRU-style eviction, preventing unbounded process-lifetime growth from streams of unique cwd values.
memory_write_pagetool description and routing prompts now steer agents toward writing the page title as a# H1on the first line ofbodyand omitting thetitleargument. ai-memory already auto-derived the title from# H1(or path stem) whentitlewas missing — the change is documentation only, but it eliminates a known source of MCPJSON parsingerrors when the LLM failed to escape quotes/colons intitle([#67]).- Custom
--web-ui-dirfrontends no longer serve raw/index.htmlwithout base-path injection; direct index requests and SPA fallback routes now return the injected shell, while static assets remain untouched ([#65]). move-projecttrue moves now run through a wiki mutation gate: normal page writes/reindexes validate the(workspace_id, project_id)pair before touching disk, while true moves hold the exclusive side across the directory rename and DB re-stamp. Stale old-workspace writes now fail without creating orphan files, and V18 aborts if existing split-brain rows are present ([#60]).move-projectcopy-purge conflict detection now treats body, frontmatter, title, tier, and pinned status as the page identity underon_conflict=block, preventing metadata-only overwrites from slipping through ([#60]).memory_write_pagecalls that specifyprojectwithoutworkspacenow default to the active workspace published by hooks, and project-only reads use the same active-workspace resolution so the write can be read back without an explicit workspace ([#61]).memory_read_pagenow accepts explicitworkspace+projectfor sibling projects and falls back to the stored DB body only when the markdown file is missing, not when the disk source of truth is corrupt or unreadable ([#63]).openai-oauthnow speaks the current ChatGPT/Codex responses stream format for bootstrap/consolidation requests and avoids sending the unsupportedmax_output_tokensfield on that endpoint ([#64]).ai-memory write-pagenow resolves an omitted--projectthrough the same current-project heuristic asread-pageandsearch, preventing writes from landing inscratchwhile the read-back targets the cwd-derived project ([#66]).
0.8.1 - 2026-05-30
Fixed
- Consolidation no longer fails on long sessions (~5,000+ observations or
multi-hour agent runs). Two bugs surfaced trying to consolidate a real
16-hour / 7,234-observation session:
- Prompt confusion (regression from the v0.8
slot_kindwork): the multi-page consolidator prompt listedslot_kindvalues (state/invariant) immediately above thetiervalues (working/episodic/semantic/procedural). The LLM read them as one list and emittedtier: "state"in structured responses, which deserialisation rejected. Prompt now leads withtier(with explicit "EXACTLY ONE OF FOUR strings" emphasis), thenkind, thenslot_kindunder its own clearly-scoped section that states "completely unrelated to tier" and "only for_slots/*paths." - No token budget on the observation dump:
build_requestandbuild_batch_request_with_slotsdumped every observation into the prompt buffer, which exceeded the provider's 200k-token context on long sessions (the sabadell run produced a 235k-token request → 400 from the provider). Newwindow_observations_to_budgetwalks the slice from most-recent backward, keeping each entry whose render cost fits in a 400k-char budget (~100k tokens), leaving room for the system prompt + schema + LLM output. When entries are skipped, a prepended note tells the LLM the context is partial so its summary doesn't pretend to cover the early session. BothPreCompactandmemory_consolidatetriggers benefit from the fix — both were silently failing into thewarn!()catchall on sessions this long. - 5 unit tests guard the windowing invariants (empty input, fits-under- budget passthrough, most-recent-preserved, single-too-large-obs drops everything, observation-boundary alignment). No schema change, no config knob, backward-compatible for sessions that already fit.
- Prompt confusion (regression from the v0.8
0.8.0 - 2026-05-30
Added
- Multi-user attribution (v0.8 Phase 1, rolling out across milestones
P1.1–P1.8). ai-memory's data model stays single-tenant — every
authenticated request sees every page — but writes can now be
attributed to a named user. Five
ai-memory usersubcommands (add,list,expire,revive,rotate-token) manage auserstable; the auth middleware resolves every request to one of four tiers (Anonymous, Root, DB user, 401), injects anExtension<ActorContext>+Extension<AuthLevel>for downstream consumers, and gates the root-only admin user-management endpoints. Tokens are 32 bytes of OS CSPRNG, stored only asSHA-256(token || ":" || token_pepper)(per-server pepper from[auth].token_pepper, auto-generated onai-memory init); seedocs/users.mdfor the SHA-256-not-argon2id rationale, the four-rung auth ladder, and the backward-compat migration for pre-v0.8 installs. New v0.8 fields on[auth]:root_username/root_email/root_name(label for the bearer token's writes) andtoken_pepper. Per-pageauthor_id+ web UI surfacing lands in P1.6/P1.7; this milestone set ships P1.1 (ActorContext+UserIdin core), P1.2 (table + writer/reader ops + V14 migration), P1.3 (auth middleware), P1.4 (root-gatedPOST/GET /admin/users+…/expire|revive|rotate-token), and P1.5 (CLI subcommands). No behaviour change for existing single-user installs: without[auth].token_pepperthe multi-user lookup stays dormant, user-management endpoints 503 with a clearmulti-user not enabledmessage pointing atai-memory init, and the existingbearer_token-only flow keeps authenticating exactly as before. memory_query { global: true }— cross-project global search that reaches every project in every workspace in one call, with each hit annotated by its workspace + project so the agent can tell where it came from. Use when the agent doesn't know which project holds a cross-cutting note (shared infra/ops, a sibling app). Mutually exclusive withscopes/project/workspace. Routing snippet +MEMORY_INSTRUCTIONSnow teach both broadening modes (scopesfor named siblings,global=truefor unknown locations) and explicitly warn thatmemory_queryreturns snippets — usememory_read_pagefor full bodies. The prompt-surface contradiction the original PR shipped ("there is no global 'search everything' mode" right after the bullet advertisingglobal=true) was caught in the post-merge audit and rewritten; the prompt regression test now refuses any variant of that legacy phrasing ([#56], thanks @djalmajr).- Cross-project wiki links + dependency graph. Wikilinks gain an
explicit scope qualifier:
[[project:path.md]]for a sibling project in the same workspace,[[workspace/project:path.md]]for another workspace. Bare links are unchanged (resolve within the source's own project).links.to_workspace/links.to_projectjoin the primary key so the sameto_pathcan land in two different projects without colliding.memory_lintnow reports dangling cross-project refs (typo'd project vs missing/renamed target page),memory_briefingexposescross_project_dependents/cross_project_dependenciesper project, andGET /api/v1/graphreturns the resolved cross- project edges for a graph view. Migration V13 rebuilds thelinkstable preserving existing rows as(to_workspace=NULL, to_project=NULL)— same "local" semantics as before ([#57], thanks @djalmajr).
Changed
- FTS5 queries OR-join bare multi-word inputs instead of the
pre-existing AND default. A natural-language query like
"have we discussed cross project search strategy"previously required every word to co-occur in one page — near-zero recall for multi-word queries, which the caller silently mistook for "never recorded". OR + BM25 ranking (callers alreadyORDER BY rank) keeps the best-matching pages at the top of the list, so the user-visible top-N is still AND-ish; OR just adds a relevant tail instead of returning nothing. Explicit FTS5 syntax (OR/AND/NOT/NEAR, quoted phrases, parens) is detected and preserved verbatim so the exact-match escape hatch stays available. 5 new unit tests guard the preservation contract (post-merge audit). Migration V12 rebuilds the FTS tables withunicode61 remove_diacritics 2so accent-free Portuguese queries ("descricao da sessao") match accented stored text ("descrição da sessão"); contentless FTS — source rows untouched ([#58], thanks @djalmajr). - MCP write tools now honour the session's project (and create
named projects on demand). Three correctness fixes on
memory_write_page/memory_lint/memory_forget_sweep:- A
memory_write_page { project: "X" }for a project name that doesn't exist used to silently fall through to the session's active project (find-only resolution); writes meant for a fresh project polluted the current one. A newwrite_target_idshelper uses get-or-create for an explicit project name, so a named write always lands where the agent asked. memory_lint+memory_forget_sweeppreviously always targeted the server's baked--projectregardless of the session, so a cross-project lint or retention sweep could never reach the project the user was actually working in. Both now resolve through the same find-onlyeffective_ids_for_read_argspath the read tools use, with the hook-published active project as the fallback.- Both
lint/sweepand the newwrite_pageadd explicitworkspace+projectargs (defaulted to current session, documented with the v0.5.2 "Omit unless the user explicitly names a different project." tail). 2 regression tests cover "Bug B" (explicit-project write must create + land) and "Bug C" (sweep must evaluate the named project, not the baked default) ([#59], thanks @djalmajr).
- A
0.7.1 - 2026-05-29
Fixed
install-hooks --agent codexno longer panics withindex not foundwhen~/.codex/config.tomlcarries an[mcp_servers]table that has other MCP servers (context7, node_repl, …) but noai-memoryentry — a perfectly valid setup since ai-memory can integrate via hooks alone.infer_codex_mcp_configusedtoml_edit's panickingIndeximpl with bare[]chains; it now walks the table via.get()and returnsNoneon any missing key. Mirrors the safe pattern the JSON variant has used all along. Adds 4 regression tests covering missing-entry, missing-table, empty-doc, and bare-entry inputs ([#53], thanks @Otavio-Machado-Santos).install-hooks --agent claude-codeno longer silently stages 0 scripts and pointssettings.jsonat an empty directory. On macOS — and any install where the binary lives outside the repo and the system package paths (/usr/local/share,/usr/share) are absent —resolve_hooks_dirfell through to the data-local candidate, which was also the staging destination. The wipe-then-copy flow insidestage_hook_scripts_inthen deleted the very scripts it was about to read, leaving 0 copied; the caller proceeded to rewritesettings.jsonanyway, disabling capture with no error. The function now (a) canonicalizes source and destination paths, skips the wipe + copy when they match and verifies in-place, preserving any scripts a priorsetup-agentrun extracted there, and (b) bails with an actionable error pointing at--hooks-dirorai-memory setup-agentwhenever zero scripts are present in either branch. Adds 3 regression tests ([#52], thanks @Otavio-Machado-Santos).- macOS thin-client wrapper no longer crashes with "Permission denied" in
the log file appender. The
bin/ai-memorywrapper passed-u $(id -u):$(id -g)to the one-shot helper container, which on macOS collides with the data volume owner (uid 1000 inside the container vs uid 501/502 on the host). The wrapper now skips-uon Darwin so the container runs as its default uid 1000 — Docker Desktop's file-sharing layer handles host ownership transparently — while Linux and other Unix systems continue to receive-u. Same change also hardens the${TTY_ARGS[@]}/${NETWORK_ARGS[@]}/${ENV_ARGS[@]}/${USER_ARGS[@]}expansions forset -ucompatibility on macOS's default bash 3.2 ([#51], thanks @abnersajr; supersedes [#50]).
0.7.0 - 2026-05-29
Added
memory_read_pageMCP tool (read-only) for fetching the FULL body of a wiki page — passpathfor a direct lookup orqueryto fetch the top FTS5 hit's full body. Complementsmemory_query's 24-word snippets when an agent needs to read an entire decision page end-to-end. Also exposed asGET /admin/read-page?workspace=…&project=…&path=…(admin HTTP) and the newai-memory read-pageCLI subcommand (thin HTTP client). All three surfaces scope to the current project by default and route user-supplied paths throughPagePath::new, so traversal attempts (../etc/passwd) are rejected with- ARCHITECTURE.md's MCP-tool table grows from 12 to 13 rows ([#49]).
_slots/*.mdpages can now declareslot_kind: stateorslot_kind: invariantfrontmatter.stateremains the default for existing slots;invariantmarks high-resistance project context or preferences that consolidation should not rewrite unless observations directly contradict the existing slot content ([#47], closes [#14]).
Fixed
- Windows PowerShell hooks no longer hang or stall the agent. The shared
hooks/lib/ai-memory-hook.ps1read stdin via[Console]::In.ReadToEnd(), which blocks indefinitely when the agent does not close the stdin pipe (observed on Claude CodePreCompact); because theInvoke-WebRequesttimeout only starts after the read returns, a stuck read meant the hook never POSTed anything. Stdin is now read asynchronously, guarded by[Console]::IsInputRedirectedwith a 2s cap, so the hook can never freeze. HTTP timeouts were also raised from 1s to 3s (POST) / 2s (handoff GET) to tolerate remote servers over higher-latency links. The full raw payload is still forwarded (parity with_lib.sh), so observation title/body stay intact. Affects every agent still on the PowerShell hook runner (Codex, Cursor, Gemini CLI, Antigravity, OpenCode on Windows) ([#48]). - Page upserts now treat frontmatter/title/tier/pinned changes as real page updates instead of short-circuiting solely on unchanged body text, keeping the SQLite index consistent with markdown frontmatter-only edits ([#47]).
0.6.1 - 2026-05-28
Added
Cache-Control: private, max-age=Nheaders on all/api/v1read endpoints (lists/search/recent/briefing/overview: 30–60s; single-page reads: 300s). Errors stay uncached. A polling SPA no longer hits the DB on every request.- ETag + conditional GET on the single-page read endpoint
(
GET /api/v1/workspaces/{ws}/projects/{p}/pages/{*path}): the response carriesETag: "<sha256>"over the markdown body, and a follow-up request with matchingIf-None-Matchreturns304 Not Modifiedwith no body. --cors-allow-originflag (repeatable) andAI_MEMORY_CORS_ALLOW_ORIGINS=a,b,cenv var. When set, aCorsLayeris attached only to/api/v1(/mcp,/hook,/admin, and/webare intentionally untouched) so a separately-hosted SPA can call the API. Each origin must include a scheme;*is rejected at startup (CORS spec forbids credentials + wildcard). Empty list = same-origin only, unchanged behaviour.
0.6.0 - 2026-05-28
Added
- Read-only
/api/v1JSON surface for third-party frontends: workspaces, projects, pages (list + read with frontmatter, body, resolved links, and back-links), recent, briefing, search (GET single/global + POST multi-scope capped at 25 scopes), and workspace/projectoverviewaggregates (handoff + briefing + memory-health drill-down). Mounted before the bearer + host-allowlist middleware so existing auth applies automatically. Read-only by construction — zero writer calls in the handlers ([#7]). --web-ui-dirflag onai-memory serveto host any static SPA at/web(same origin as the API, behind the same auth), withindex.htmlSPA fallback viatower-http::ServeDir. Validates the directory exists and containsindex.htmlbefore binding. When the flag is absent, the built-in server-side/webbrowser stays the default ([#7]).- MCP read tools (
memory_query,memory_recent,memory_status,memory_briefing,memory_explore) accept optionalworkspace+scopesargs for explicit multi-project queries; existing single-projectbehaviour is unchanged and remains the default ([#7]). - New reader queries powering the API: per-page outgoing links + incoming back-links, workspace-aggregated briefing, memory-health (stale / duplicate / orphan) counts and drill-down lists, workspace summaries with last-update timestamps ([#7]).
Fixed
- Antigravity
pre-tool-usehook now emits the documented{"decision":"allow"}JSON contract instead of an empty{}, while keeping theai_memory_post_hookcall fully suppressed (>/dev/null 2>&1 || true) so thequeuedbody never bleeds into the hook's stdout. Identical logic for.shand.ps1; other hook scripts remain silent and unchanged ([#44], thanks @ArtroxGabriel).
Docs
- New
docs/frontend-api.mdintegration guide for/api/v1: auth flow, response schemas (PageHit,BriefingSnapshot,HealthDetail,PageLinks, …), error model, limits/pagination, custom-UI hosting, a workedfetch/curlexample, and pointers to the canonical source-of-truth files.
0.5.2 - 2026-05-28
Added
ai-memory status/status --jsonnow includes passive process-scoped LLM and embedding provider health based on the last real provider call, without active probing or token spend ([#46]).
Changed
- Agent-facing prompts (
MEMORY_INSTRUCTIONS, theCLAUDE.md/AGENTS.mdrouting snippet, and the per-toolproject/cwdarg docstrings) now lead with a clear "default to the current project — do not passprojectorcwdargs unless the user names a different project" rule, plus a reminder that the SessionStart auto-fetched handoff block already covers the current project. Reduces cross-agent friction where a fresh agent surfaced the wrong project's handoff because the LLM over-eagerly passed scoping args. Doc-only, no behaviour change.
Fixed
- Claude Code hook installs on native Windows now render Git Bash-compatible
bash -ccommands that keep the POSIX.shhook scripts and convert drive-letter paths to Git Bash paths, matching Claude Code's actual hook runner instead of emitting PowerShell commands ([#45]). ai-memory llm-test --provider anthropic-oauthnow parses and maps to the Anthropic OAuth provider instead of being rejected by clap ([#43]).
[0.5.1] - 2026-05-27
Changed
- Docker release publishing now builds Linux x86_64 and aarch64 artifacts once, reuses those artifacts for Docker images, and smoke-tests both amd64 and arm64 images after assembling the multi-arch manifest.
- The AUR
ai-memory-binpackage now supports aarch64 using the prebuilt Linux aarch64 release artifact. - Docker source builds now use the vendored Tailwind CSS artifact, avoiding cross-architecture Tailwind CLI cache collisions during multi-arch releases.
0.5.0 - 2026-05-27
Fixed
- Docker release images now publish both
linux/amd64andlinux/arm64manifests, so Apple Silicon and ARM64 Linux hosts can pull the image without forcing x86 emulation ([#41]).
0.4.0 - 2026-05-27
Added
anthropic-oauthLLM provider: use a Claude Pro/Max subscription viaclaude setup-tokeninstead of an API key. In-Rust, reuses the existing Anthropic Messages client (incl. structured output). Unofficial and against Anthropic's usage policies — use at your own risk (docs warn prominently).- Opt-in
AI_MEMORY_CONSOLIDATE_ON_SESSION_END: when set and an LLM provider is configured, SessionEnd additionally runs LLM consolidation on top of the always-written rule-based summary page (non-fatal on failure) ([#40]).
Changed
- Docs recommend a small/fast model (Haiku/mini class) for the OAuth / subscription LLM backends — consolidation/lint/explore is summarisation, not hard reasoning, and small models are far easier on subscription rate limits.
- Aligned every prompt surface + doc with actual SessionEnd behavior: it always
writes a rule-based summary page + handoff; LLM consolidation runs on
PreCompact, on demand via
memory_consolidate, and at session end only behind the new opt-in flag ([#40]).
Fixed
- Windows own-write detection:
inode_ofnow returns the real NTFS file index (was always0, which collapsed the watcher's own-write set) ([#37]). ai-memory upgradeno longer fails withinvalid value 'lib' for --agent— the hook-refresh loop skips the sharedlib/helper dir ([#38]).- Native packaging CI now supports non-root runners whose
systemd-tmpfileslacks--dry-run, while still operating only inside a temporary alternate root.
0.3.2 - 2026-05-27
Fixed
- AUR release publishing now runs with
HOME=/home/aurbuildand an explicitGIT_SSH_COMMAND, so the workflow uses the configured AUR deploy key.
0.3.1 - 2026-05-27
Changed
- Reissued the release after the initial AUR publish failure. This release was superseded by 0.3.2 for the AUR SSH home fix.
0.3.0 - 2026-05-27
Added
- Arch Linux native packaging assets: source and prebuilt AUR package definitions, system/user systemd units, sysusers/tmpfiles entries, native config/env templates, CI-safe alternate-root packaging checks, and a manual disposable-distrobox integration harness for validating real service startup before publishing.
- Tag-triggered release automation now validates that
vX.Y.ZmatchesCargo.toml, publishes a native Linux release tarball, keeps Docker image publishing behind Docker Hub secrets, and optionally publishes both AUR package bases whenAUR_SSH_PRIVATE_KEYis configured. memory_write_pageMCP tool for explicit durable annotations, so agents can write permanent wiki knowledge without abusing single-use handoffs.openai-oauthLLM provider for ChatGPT/Codex accounts, includingai-memory auth login|logout|statusdevice-flow commands and token storage in<data_dir>/auth.json.copilotLLM provider for GitHub Copilot Chat accounts. It stores a GitHub token viaai-memory auth login copilot, exchanges it for a short-lived Copilot API token, and sends Copilot Chat requests withvscode-chatintegration headers.
Fixed
install-mcp,install-hooks, andsetup-agentnow honor configuredAI_MEMORY_SERVER_URLdefaults;install-hooksalso reuses an existing ai-memory MCP entry when present, preventing remote MCP setups from regenerating loopback-only lifecycle hooks during installs/upgrades.- Filesystem watcher now reindexes a project when backends report only a parent-directory event, improving external editor capture on macOS/FSEvents.
- OpenAI strict structured-output schema normalization now strips generated
$refannotation siblings and rewrites generated enumoneOfschemas toanyOf, unblockingmemory_consolidate multi_page=trueon OpenAI models. - OpenAI-compatible embedding calls now truncate oversized page bodies, surface
provider errors returned in HTTP 200 bodies, retry bounded HTTP 429 responses,
and may reuse
LLM_API_KEYwhen a custom embedding base URL is configured. ai-memory embed --forcewithout--projectnow re-embeds every project in the workspace and purges stale/superseded embedding rows in the same scope.- Windows hook
cwdvalues sent to a Linux server now resolve projects by the final path component instead of treating the full backslash path as the project name.
0.2.0 - 2026-05-26
Added
ai-memory bootstrapnow prunes collected sources before POSTing to the server and supports--chunk-input-tokensto process large repositories via sequential LLM calls instead of one oversized prompt.- Opt-in extension event metadata for
/hook: custom integrations can passextension=<namespace>(and optionallysource_event=<name>) to preserve a validated third-party source event while storage keeps the canonicalObservationKindclosed. Unknown events without an extension still collapse tootherwith no source-event metadata. .ai-memory.tomlmarker file lets a directory tree declare itsworkspace(required) andproject(optional) without depending onbasename($cwd). Lifecycle hook scripts walk up fromcwdto find the closest marker and forwardcwdplus the declared names as query params onPOST /hookandGET /handoff. Markers can also setproject_strategy = "repo-root"to derive project identity from the main git repository root, so linked worktrees share one project. Server accepts the new params as optional overrides; absent marker means the previous behaviour (workspace = "default",project = basename(cwd)) — fully backward compatible. Seedocs/marker-file.md.- Oh My Pi / OMP is now a first-class integration:
install-mcp --client piand--client ompwrite native~/.omp/agent/mcp.jsonconfig, whileinstall-hooks --agent ompand--agent piwrite the TypeScript extension used for lifecycle capture and handoff injection. - Graph-aware retrieval:
memory_querynow combines FTS5, wikilink-neighbor expansion, optional vector RRF, and bounded raw-observation fallback. - Observation FTS indexing and unresolved-link diagnostics surfaced through admin/CLI status paths.
_slots/wiki pages are automatically pinned and surfaced in briefing / explore snapshots.- Server-side scheduled maintenance for forget sweep and lint, with optional embedding backfill scheduling.
- Experimental native Windows support: PowerShell Docker wrapper,
ai-memory.cmd,.ps1lifecycle hooks in parity with.shhooks, Windows Tailwind hash/download support, anddocs/windows.md. - Google Gemini LLM provider via
AI_MEMORY_LLM_PROVIDER=gemini, withgemini-2.5-flashas the default hosted Google model andGEMINI_API_KEY/GOOGLE_API_KEYsupport. - Google Gemini embeddings via
AI_MEMORY_EMBEDDING_PROVIDER=googleorgemini, withgemini-embedding-001as the default embedding model andGEMINI_API_KEY/GOOGLE_API_KEYsupport. - Antigravity CLI (
agy) support for MCP config (serverUrl) and lifecycle capture through itsPreInvocation,PreToolUse,PostToolUse, andStophook events. - README support matrix for operating systems, agent integrations, LLM providers, and embedding providers.
ai-memory uninstall— removes ai-memory's hooks, MCP registration, and CLAUDE.md/AGENTS.md instruction block across all detected agents (dry-run by default;--applyto execute, with timestamped backups).--purge-datawipes wiki/db/raw via the reset guard.--only hooks|mcp|instructionsto narrow. MCP matching is endpoint-based by default; pass--mcp-urlwhen the server was installed with a custom endpoint and--mcp-nameonly to narrow removal to one matching entry. Docker/volume teardown is printed as a hint, not executed.
Changed
- Same-body page upserts are now true no-ops, avoiding periodic watcher reconcile writes, FTS churn, and misleading recent-page timestamps.
- Graph-neighbor expansion for hybrid search now batches all seed pages into one SQL query instead of issuing incoming/outgoing lookups per seed.
- Embedding backfill stores embeddings in chunks instead of one writer command and SQLite transaction per page.
- Hook ingestion now bounds in-flight processing and returns HTTP 429 when saturated instead of spawning unbounded background tasks.
- Documented the vector backend policy and the measured criteria required
before adding
sqlite-vec. - Clarified Gemini CLI support docs: MCP registration, lifecycle hooks, SessionStart handoff injection, and SessionEnd capture are now called out consistently across README and install guides.
- Added OpenClaw lifecycle support via a generated native plugin package and updated Cursor / Claude Desktop / OpenClaw support docs against current upstream MCP and hook documentation.
- Docker images now bundle both POSIX and PowerShell hook scripts.
ai-memory uninstall --purge-datanow previews thewiki//db//raw/wipe in dry-run (mirroringreset) and refuses up front if anai-memoryprocess is alive (all-or-nothing) instead of removing the wiring and then skipping the purge. The data wipe is now shared withresetvia a single internal helper.ai-memory uninstallonly deletes generated plugin/extension files after re-validating their ai-memory-generated content, and never treats a matching filename or MCP server name alone as proof of ownership.
Fixed
servenow warns and starts when stored embedding rows were created with a different(provider, model, dim)than the current config. Hybrid search ignores stale rows untilai-memory embed --forceor scheduled backfill re-embeds them, avoiding the previous startup deadlock.- Session capture now persists every documented agent kind (
cursor,gemini-cli,claude-desktop,openclaw,omp/pi) instead of failing thesessions.agent_kinddatabase CHECK for agents added after the initial schema. memory_handoff_beginandmemory_handoff_acceptnow resolve the active project the same way the briefing/search tools do, so MCP handoffs land in the project currently reported by hooks instead of the server's baked default project.- Natural-language
memory_querytext containing bare colons, such aspick: handoff, no longer trips FTS5 column syntax errors while explicit FTS operators likequick OR slowremain supported. - Marker-file routing now reaches the generated OpenCode and OMP
TypeScript hook integrations, not only the POSIX/PowerShell script
hooks. POSIX helpers also preserve the outer hook
cwdwhen nested tool payloads contain their owncwd, and encode+correctly in marker-derived query parameters. backup --tonow streams the tarball to disk instead of buffering the full archive in CLI memory.- Hyphenated FTS5 queries such as
ai-memoryare normalized safely instead of being parsed as column operators. - Gemini 2.5 Flash requests disable default dynamic thinking so hidden thought
tokens do not consume
maxOutputTokensand truncate strict JSON responses. install-mcp --client claude-codenow prints the direct-edit JSON path as~/.claude.json, matching the--applypath andclaude mcp addbehavior.- Hook routing now evicts a stale project-cache entry and retries once when a
live server sees a cached project deleted underneath it, such as after
purge-project, so capture resumes without restarting the server. - Session-start handoff hooks now include
cwdeven without a marker file, so defaultproject = basename(cwd)projects receive pending handoffs without requiring.ai-memory.toml. ai-memory uninstallnow removes only ai-memory commands from mixed nested hook entries, preserves third-party commands in the same matcher, and removes legacy Codex inline-table MCP entries.- Generated POSIX hook commands now shell-quote script paths and env values with metacharacters, fixing custom hook directories containing spaces and preventing shell-active token/URL fragments.
- OpenClaw's generated plugin now forwards marker-file routing params just like the OpenCode and OMP generated integrations.
- The Linux/macOS Docker wrapper now lets thin-client commands such as
statusandbootstrapreach the local quick-start server bound on the host's127.0.0.1:49374.
0.1.3 - 2026-05-24
Added
ai-memory lint --no-llm(andmemory_lintno_llmarg) to run only the rule-based lint pass while leaving the LLM enabled formemory_explore/memory_consolidate([#4]).
Fixed
memory_lintLLM contradiction pass silently never contributed: theLintFindingstruct expectedseverity/messagebut the prompt asked forsummary/detail. The prompt is now aligned to the canonical shape and the struct tolerates both (defaultsseverity, aliasessummary→message, captures optionaldetail) ([#4]).- Reasoning models (MiniMax M2.7, DeepSeek, Qwen, Kimi) that emit
<think>…</think>/<analysis>…</analysis>blocks before the JSON broke structured-output parsing (key must be a string at line 1 column 2). The openai-compat provider now strips reasoning blocks and surrounding markdown fences before extracting the JSON object, so lint / consolidate / bootstrap work with reasoning models ([#5]). - openai-compat base URLs with non-
v1version segments (e.g. Z.AI's/v4) or a full endpoint path no longer produce…/v1/v1/…404s ([#6], thanks @lucasliet).
0.1.2 - 2026-05-24
Changed
- HTTP transport now defaults to stateless mode (
json_response, noMcp-Session-Idrequired), so stateless MCP clients (OpenCodetype: "remote",curl) work without anmcp-remotestdio shim ([#3]). Newserve --transport http --http-statefulflag restores the previous session+SSE behaviour for clients that need it.
0.1.1 - 2026-05-24
Added
- Wiki-structure migration framework:
wiki_migrationsSQL table (V06),WikiMigrationtrait, migration registry, andrun_pendingrunner invoked at server startup before the watcher starts. - MCP read tools (
memory_query,memory_recent,memory_status,memory_briefing,memory_explore) accept an optionalprojectargument to target a specific project on a shared server.
Fixed
- OpenCode hook events (
tool.execute.*,session.*) were rejected with "missing session_id" because OpenCode sendssessionID(capitalID) and the extractor only matchedsessionId. All spellings are now accepted ([#1]). - MCP read tools were locked to the server's static
--project(defaultscratch), so on a shared HTTP server they returned empty memory even while hooks populated the correct per-cwd project. The hook router now publishes the active project to a shared pointer that the read tools use as their default; an explicitprojectargument overrides it ([#2]).
0.1.0 - 2026-05-23
Added
- Per-project UUID-namespaced wiki layout: pages live at
<wiki_root>/<workspace_id>/<project_id>/<page-path>. Rename is now a single column update; purge isremove_dir_allon the project dir. - CLI becomes a thin HTTP client:
bootstrap,status,search,reorg,lint,forget-sweep,embed,commit,backup,write-pageall delegate to the running server via/admin/*routes. The server is the sole writer of wiki + SQLite. purge-projectcommand with cascade-delete indexes and per-project isolation guard (refuses to delete files claimed by sibling projects).rename-projectcommand: column-only rename, no file moves.memory_install_self_routingMCP tool: installs the agent-routing snippet into CLAUDE.md / AGENTS.md /.cursorrulesin one call.- Read-only HTTP wiki browser (
/web) with project tree, page view, and full-text search. - Bearer token auth (
AI_MEMORY_AUTH_TOKEN/generate-auth-token), Host-header allowlist, and 10 MB body cap for the HTTP server. backup/restorecommands using.tar.gzarchives with live-process guard (refuses to run if anotherai-memoryis active on the same data dir).- Per-cwd project routing in hooks: observations route to the project matching the agent's working directory, not the server default.
opencode/openclawaliases for the OpenCode MCP client.- Dockerised CLI wrapper (
bin/ai-memory) with auto-restart for the local container and nudge for remote upgrades. bootstrapserialises parallel runs to prevent duplicate project creation and handles the case where the CWD has no git repo.- Monthly log-md rotation to keep
log.mdfrom growing unbounded. memory_consolidatePreCompact checkpointing falls back to rule-based summarisation when no LLM is configured.docs/lifecycle-ops.md: safety matrix for state-touching commands (reset, restore, purge-project, rename-project).docs/wiki-migrations.md: when and how to write a wiki migration.
Changed
bin/ai-memoryforwardsAI_MEMORY_SERVER_URLand no longer creates-wmount-conflict directories.bootstrapresolves the repo root vialibgit2, removing thegitbinary dependency.- Admin routes consolidated: dry-run support, correct status codes, deduplicated handlers.
- Host-header allowlist sourced from
Config.allowed_hosts; logged at startup so operators can verify the effective list.
Fixed
AI_MEMORY_HOST_CWDhandling and dry-run no-project side effects.- Web page view: strip leading H1 from body to prevent title duplication.
install-mcpCodex config key wasbearer_token, nothttp_headers/headers.- Consolidator used server startup default project instead of the session's actual project.