create-ai-memory 0.1.0 → 0.1.1

package/README.md

@@ -1,20 +1,31 @@
 <div align="center">
 
-# ai-memory
+# create-ai-memory
 
-**Persistent, agent-agnostic session memory for AI coding CLIs. One Markdown vault, any agent.**
+**The persistent memory layer for AI coding agents. One Markdown vault, every CLI.**
 
-Give Claude Code, Codex, Gemini, Cursor, and opencode a shared second brain that
-survives across sessions: durable profile, per-project context, and last-session carryover,
-injected at launch. The vault is the source of truth; the chat is disposable.
+Your agent forgets everything the moment a session ends. create-ai-memory gives Claude
+Code, Codex, Gemini, Cursor, and opencode a shared second brain: a plain-Markdown
+vault that carries your profile, each project's context, and where you left off
+into every new session, on its own.
 
-No daemon, no database, no API key. Just zsh and Markdown files you can read.
+No daemon. No database. No API key. Just zsh and Markdown you can read.
 
+```sh
+npm create ai-memory@latest
+```
+
+[![npm](https://img.shields.io/npm/v/create-ai-memory?color=cb3837&label=npm)](https://www.npmjs.com/package/create-ai-memory)
 ![zsh](https://img.shields.io/badge/shell-zsh-89e051)
-![tests](https://img.shields.io/badge/tests-35%20passing-brightgreen)
+![tests](https://img.shields.io/badge/tests-38%20passing-brightgreen)
+![deps](https://img.shields.io/badge/runtime%20deps-0-blue)
 ![license](https://img.shields.io/badge/license-MIT-blue)
 ![PRs](https://img.shields.io/badge/PRs-welcome-orange)
 
+<br>
+
+<img src="https://raw.githubusercontent.com/rambaarde/create-ai-memory/main/assets/demo.gif" alt="Installing create-ai-memory with npm create ai-memory@latest" width="820">
+
 </div>
 
 ---
@@ -41,9 +52,10 @@ or none. Knowledge earned in Claude doesn't reach Codex.
 ## How it works
 
 Keep the memory outside the chat, in plain Markdown on disk, and inject it into
-whichever agent you launch. Because it's just files, the vault doubles as an
-[Obsidian](https://obsidian.md) folder with graph view, backlinks, and search;
-nothing here requires Obsidian.
+whichever agent you launch. A chat thread is disposable; the vault is permanent.
+Because it is just files, the same vault opens as an
+[Obsidian](https://obsidian.md) second brain with graph view, backlinks, and
+search. Nothing here requires Obsidian; it is Markdown either way.
 
 Memory sits in three layers, each injected at the right scope:
 
@@ -53,10 +65,13 @@ Memory sits in three layers, each injected at the right scope:
 | **Project** | `_projects/<repo>.md` | sessions in that repo | purpose, architecture, constraints, active decisions |
 | **Session** | `_session_logs/<repo>/<timestamp>.md` | next session as carryover | what changed, blockers, next steps |
 
+When you run a launcher, create-ai-memory assembles those layers into one prompt and
+hands it to the agent as its opening message:
+
 ```
   $ claude-start
         │
-        ├─ resolve project from the current git repo
+        ├─ resolve the project from the current git repo
         ├─ create a fresh session log from the template
         ├─ gather:  Global Profile + Standards         (who you are)
         │           Project note                        (this repo)
@@ -73,10 +88,10 @@ Memory sits in three layers, each injected at the right scope:
         → the NEXT session inherits it as carryover
 ```
 
-One environment variable, `AI_MEM_ROOT`, points at the vault, so the system moves
-between machines by pointing at the same folder.
+One environment variable, `AI_MEM_ROOT`, points at the vault, so the whole system
+moves between machines by pointing at the same folder.
 
-## A session, start to finish
+## See a full session
 
 ```console
 $ cd ~/code/checkout-api
@@ -124,7 +139,8 @@ off last time.
 
 - [The problem](#the-problem)
 - [How it works](#how-it-works)
-- [A session, start to finish](#a-session-start-to-finish)
+- [See a full session](#see-a-full-session)
+- [What you get](#what-you-get)
 
 **Getting started**
 
@@ -138,9 +154,9 @@ off last time.
 **Reference**
 
 - [Session skills](#session-skills-optional)
-- [Vault layout](#vault-layout)
-- [Adding a new agent](#adding-a-new-agent)
-- [Optional integrations](#optional-integrations)
+- [Your vault](#your-vault)
+- [Add another agent](#add-another-agent)
+- [Integrations](#integrations)
 - [Configuration](#configuration)
 
 </td>
@@ -148,15 +164,31 @@ off last time.
 
 **Project**
 
+- [Why plain files](#why-plain-files)
 - [Tests](#tests)
-- [Design notes](#design-notes)
+- [FAQ](#faq)
 - [Roadmap](#roadmap)
+- [Contributing](#contributing)
 - [License](#license)
 
 </td>
 </tr>
 </table>
 
+## What you get
+
+| | |
+|---|---|
+| **Cross-agent memory** | One vault serves Claude Code, Codex, Gemini, Cursor, and opencode. Context earned in one reaches the next. |
+| **Automatic carryover** | A Stop hook writes the branch, the commits you made, and uncommitted changes into the session log, so tomorrow's run resumes where today's ended. |
+| **Per-project context** | Each git repo gets its own note for purpose, architecture, and decisions, injected only for that project. |
+| **Your rules, everywhere** | A global profile and standards note ride along in every session, on every project. |
+| **Session skills you define** | Register your own y/n launch options (terse output, design review, minimal-code). create-ai-memory ships none; they are yours. |
+| **Open agent model** | Adapters are three lines. Add opencode, aider, or anything with a CLI without touching the core. |
+| **Obsidian-native** | The vault is plain Markdown, so it opens as an Obsidian second brain with graph view and backlinks, or as plain files with grep. |
+| **Guardrails built in** | Every write is checked to stay inside the vault, and a commit hook refuses commits made without the vault context loaded. |
+| **Zero runtime deps** | No daemon, no database, no API key, no server. It runs in your shell. |
+
 ## Install
 
 Pick whichever fits how you manage your shell. All paths end at the same place.
@@ -168,6 +200,8 @@ npm create ai-memory@latest         # into ~/ai-memory, then runs the setup
 npx create-ai-memory ~/code/ai-memory   # or a directory you choose
 ```
 
+Package: [npmjs.com/package/create-ai-memory](https://www.npmjs.com/package/create-ai-memory)
+
 **zsh plugin manager:**
 
 ```zsh
@@ -180,9 +214,9 @@ rambaarde/create-ai-memory
 # oh-my-zsh: clone into custom/plugins, then add create-ai-memory to plugins=(...)
 ```
 
-Plugin-manager installs only source the module. That's fine: the vault
+Plugin-manager installs only source the module. That is fine: the vault
 auto-scaffolds from the shipped templates on first use, so `install.sh` is
-optional. Set `AI_MEM_ROOT` in `~/.zshrc` first if you don't want the default
+optional. Set `AI_MEM_ROOT` in `~/.zshrc` first if you do not want the default
 `~/.ai-memory/_Ai_Memory`.
 
 **Clone and run** (the source of truth all paths reuse):
@@ -192,7 +226,7 @@ git clone https://github.com/rambaarde/create-ai-memory.git ~/ai-memory
 ~/ai-memory/install.sh
 ```
 
-> **zsh only.** The module uses `print -r`, `${(s:|:)}`, and `select`. A bash
+> **zsh only.** The module uses `print -r`, `${(s:|:)}`, and associative arrays. A bash
 > port is welcome as a PR; see [Roadmap](#roadmap).
 
 ## Commands
@@ -208,7 +242,7 @@ Project is auto-resolved from the current git repo; pass a name to override.
 
 ## Session skills (optional)
 
-You define your own per-session skills; ai-memory ships none. At launch it asks
+You define your own per-session skills; create-ai-memory ships none. At launch it asks
 y/n for each skill you registered, then injects the chosen instruction blocks into
 the agent (and for Cursor, writes them as a managed always-apply rule). Register
 nothing and every session is plain.
@@ -228,7 +262,50 @@ source "$HOME/ai-memory/shell/ai-mem.zsh"
 The injected block applies for the whole run, so a session's chosen skills persist
 as instructions across every change the agent makes.
 
-## Vault layout
+### Recommended skills to wire in
+
+These are the session skills worth having on the picker. Each maps to a working
+Claude Code skill; if you have the skill installed, the block below tells the agent
+to use it, and the behavior still applies to agents that do not have the skill
+because the instruction is inlined. Drop them into `AI_MEM_SKILLS` and reorder to
+taste.
+
+```zsh
+typeset -gA AI_MEM_SKILLS
+
+# caveman: terse, no-filler output
+AI_MEM_SKILLS[caveman]='Terse output (caveman) this session?::Respond terse like a smart caveman. Keep technical substance exact; drop filler, pleasantries, and hedging.'
+
+# ponytail: the laziest solution that actually works (stdlib > deps, one line > fifty)
+AI_MEM_SKILLS[ponytail]='Minimal-code (ponytail) this session?::Use the ponytail approach. Prefer the standard library before new code, native platform features before dependencies, and one line before fifty. Question whether the task needs to exist at all (YAGNI).'
+
+# hallmark: anti-AI-slop UI and frontend design
+AI_MEM_SKILLS[hallmark]='Strict UI design (hallmark) this session?::Use the hallmark approach for any frontend, UI, or design work. Avoid generic AI-slop layouts; make type, spacing, color, and hierarchy intentional.'
+
+AI_MEM_SKILL_ORDER=(caveman ponytail hallmark)
+
+source "$HOME/ai-memory/shell/ai-mem.zsh"
+```
+
+| Skill | What it does | Reach for it when | Source |
+|---|---|---|---|
+| **caveman** | Strips output to terse, no-filler answers | You want signal over prose | [caveman.so](https://caveman.so/) |
+| **ponytail** | Pushes the smallest change that works; stdlib and native features over dependencies | Building features or reviewing for over-engineering | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) |
+| **hallmark** | Anti-AI-slop design discipline for UI and frontend work | Any visual or frontend task | [usehallmark.com](https://www.usehallmark.com/) |
+
+Skills are per session and independent, so you can turn on `ponytail` for a
+refactor and add `hallmark` only when you touch the UI. These are separate,
+installable Claude Code skills; the blocks above inline their behavior so a
+session still benefits even on an agent that does not have the skill installed.
+
+If you want a queryable knowledge graph of your codebase alongside your memory,
+pair create-ai-memory with [graphify](https://github.com/safishamsi/graphify).
+
+## Your vault
+
+The vault is a folder of Markdown. Point `AI_MEM_ROOT` at a new directory or at an
+existing Obsidian vault; either way you get graph view, backlinks, and full-text
+search over your own AI memory, plus plain `grep` when you want it.
 
 ```
 $AI_MEM_ROOT/
@@ -247,11 +324,11 @@ Notes are created from templates on first use and never overwritten. Edit
 `_Global_Profile.md` and `_Standards.md` to make them yours; the shipped versions
 are sanitized placeholders.
 
-## Adding a new agent
+## Add another agent
 
-Launchers aren't hardcoded. Each agent is one small adapter, and the
+Launchers are not hardcoded. Each agent is one small adapter, and the
 `<name>-start` function is generated for you. `claude`, `codex`, `gemini`,
-`cursor`, and `opencode` ship built in. To add another, say `aider`:
+`cursor`, and `opencode` ship built in. To add `aider`:
 
 1. Define the adapter in `shell/adapters.zsh`. It receives `$1` memory prompt,
    `$2` mode block, and `$3` onward extra args:
@@ -267,7 +344,7 @@ Launchers aren't hardcoded. Each agent is one small adapter, and the
    ```
 3. `aider-start` now exists. No core edits.
 
-## Optional integrations
+## Integrations
 
 ### Claude Code hooks
 The files live in `hooks/claude/`. Record repo `HEAD` at session start, then on
@@ -282,7 +359,7 @@ The files live in `hooks/git/`:
 
 - **`commit-msg`** requires Conventional Commits and a structured body, and that
   `ai-context` was loaded in the committing shell, matching a per-repo token. An
-  agent can't commit without the vault context loaded.
+  agent cannot commit without the vault context loaded.
 - **`pre-push`** blocks direct pushes to `main` unless `ALLOW_PUSH_TO_MAIN=1`.
 
 Enable per repo:
@@ -300,14 +377,36 @@ git -C <repo> config core.hooksPath .githooks
 | `AI_MEM_AGENTS` | `claude codex gemini cursor opencode` | Space-separated agents to generate `-start` functions for |
 | `AI_MEM_SKILLS` / `AI_MEM_SKILL_ORDER` | empty | Your per-session skills (see above) |
 
+## Why plain files
+
+create-ai-memory is deliberately small. There is no server to run, no container to pull,
+no database to migrate, no API key to store. The design choices behind that:
+
+- **The vault is the source of truth; the chat is disposable.** Durable state
+  lives in Markdown you can read, diff, and version, not inside any agent.
+- **Files over a service.** A folder syncs over git, Dropbox, or Syncthing, opens
+  in Obsidian, and greps in a shell. It outlives any one tool.
+- **Explicit over magic.** You decide what goes in the profile, the project note,
+  and the session log. The agent reads them; it does not silently rewrite your
+  memory behind your back.
+- **Path-guarded writes.** Every file operation is checked to stay inside
+  `$AI_MEM_ROOT`, so an agent cannot write outside the memory boundary.
+- **Project equals git repo.** Resolution prefers the repo you are standing in, so
+  moving between projects in one shell never pins the wrong project.
+
+If you want an auto-capturing server with a web UI and vector search, other tools
+do that. create-ai-memory trades those for something you can read end to end in an
+afternoon and carry anywhere.
+
 ## Tests
 
-Offline unit suite (throwaway vault + git repo, no network): path guarding,
-project resolution, session prep, context prompt, skill picker, launcher
-generation, adapter dispatch, the commit token, and `ai-note`.
+Offline unit suite (throwaway vault and git repo, no network): path guarding,
+project resolution, session prep, the context prompt, the skill picker, launcher
+generation, adapter dispatch, the commit token, `ai-note`, and the cursor rule
+file.
 
 ```sh
-zsh tests/run.sh     # offline unit tests
+zsh tests/run.sh     # offline unit tests (38 assertions)
 zsh tests/smoke.sh   # live: launches each agent headlessly, checks it responds
 ```
 
@@ -315,25 +414,50 @@ zsh tests/smoke.sh   # live: launches each agent headlessly, checks it responds
 (opencode defaults to DeepSeek; set it up or pass
 `AIMEM_SMOKE_OPENCODE_MODEL=provider/model`).
 
-## Design notes
+## FAQ
 
-- **The vault is the source of truth; the chat is disposable.** Durable state lives
-  in Markdown, not in any agent's memory.
-- **Path-guarded writes.** Every file operation is checked to stay inside
-  `$AI_MEM_ROOT`, so an agent can't write outside the memory boundary.
-- **Project = git repo.** Resolution prefers the repo you're standing in, so
-  `cd`-ing between projects in one shell never pins the wrong project.
-- **Additive by default.** Templates fill in; notes are never clobbered.
+**Does it send my code anywhere?**
+No. create-ai-memory is shell functions plus Markdown files on your disk. The only network
+calls are the ones your agent already makes.
+
+**Do I need Obsidian?**
+No. The vault is plain Markdown. Obsidian is a nice way to browse it, not a
+requirement.
+
+**Do I need an API key or a paid plan?**
+No. create-ai-memory itself needs neither. Your agents use whatever auth they already have.
+
+**Which shells and platforms?**
+zsh today, on macOS and Linux (including WSL). A bash port is on the roadmap.
+
+**Does plain `claude` still work?**
+Yes. Only the `*-start` launchers inject memory; plain runs are untouched, and the
+hooks no-op unless a session was launched through create-ai-memory.
+
+**Can I use my existing Obsidian vault?**
+Yes. Point `AI_MEM_ROOT` at it. Notes are additive and never overwrite your files.
+
+**How is a "project" identified?**
+By the directory name of the git repo you are in.
+
+**My agent isn't listed. Can I add it?**
+Yes, if it has a CLI. See [Add another agent](#add-another-agent); it is three
+lines.
 
 ## Roadmap
 
 - Bash port of the shell module.
-- Publish `create-ai-memory` to npm.
-- More agent adapters shipped by default: opencode, aider.
+- More agent adapters shipped by default: aider and others.
 - Optional cross-project index and search over session logs.
 
-PRs welcome. Persistent AI memory shouldn't be a personal hack; it should be
-something the whole community can install.
+## Contributing
+
+Issues and PRs are welcome. Good first areas: a bash port, new agent adapters, and
+docs. Run `zsh tests/run.sh` before opening a PR; keep changes additive and the
+vault path-guarded.
+
+Persistent AI memory should not be a personal hack; it should be something the
+whole community can install.
 
 ## License
 

package/bin/create-ai-memory.js

@@ -31,11 +31,14 @@ for (const item of ITEMS) {
   if (existsSync(src)) cpSync(src, join(dest, item), { recursive: true });
 }
 
-// Hand off to the shell installer for the interactive setup.
-const r = spawnSync('sh', [join(dest, 'install.sh')], { stdio: 'inherit' });
+// Hand off to the shell installer for the interactive setup. Run it with bash,
+// not sh: install.sh is a bash script (arrays, printf -v, ${!var}) and would
+// fail under a POSIX sh such as dash, which is /bin/sh on Debian and Ubuntu.
+const installer = join(dest, 'install.sh');
+const r = spawnSync('bash', [installer], { stdio: 'inherit' });
 if (r.error) {
-  console.error(`create-ai-memory: could not run install.sh: ${r.error.message}`);
-  console.error(`Files are in ${dest}; run  sh ${join(dest, 'install.sh')}  yourself.`);
+  console.error(`create-ai-memory: could not run the installer with bash: ${r.error.message}`);
+  console.error(`Files are in ${dest}; run  bash ${installer}  yourself.`);
   process.exit(1);
 }
 process.exit(r.status ?? 0);

package/install.sh

@@ -32,11 +32,14 @@ confirm() { # confirm <prompt>  -> 0 for yes; defaults to yes, and yes when pipe
   case "${__reply:-Y}" in [Nn]*) return 1 ;; *) return 0 ;; esac
 }
 
-# Color only when it lands in a real terminal that wants it.
+# Color only in a real terminal that actually supports 24-bit color. Terminals
+# that do not advertise truecolor (e.g. macOS Terminal.app) fall back to the
+# plain block art rather than rendering the gradient as wrong colors.
 supports_color() {
   [ "$INTERACTIVE" -eq 1 ] || return 1
   [ -z "${NO_COLOR:-}" ] || return 1
   [ "${TERM:-}" != "dumb" ] || return 1
+  case "${COLORTERM:-}" in truecolor|24bit) return 0 ;; *) return 1 ;; esac
 }
 
 # ANSI Shadow "AI MEMORY" with a teal->violet vertical gradient (24-bit color),
@@ -69,7 +72,7 @@ banner
 # --- gather settings ---------------------------------------------------------
 AI_MEM_ROOT="${AI_MEM_ROOT:-$HOME/.ai-memory/_Ai_Memory}"
 ask AI_MEM_ROOT   "Where should your memory vault live?" "$AI_MEM_ROOT"
-AI_MEM_AGENTS="${AI_MEM_AGENTS:-claude codex gemini cursor}"
+AI_MEM_AGENTS="${AI_MEM_AGENTS:-claude codex gemini cursor opencode}"
 ask AI_MEM_AGENTS "Which agents should get <agent>-start launchers?" "$AI_MEM_AGENTS"
 
 # --- scaffold the vault ------------------------------------------------------
@@ -88,7 +91,7 @@ copy_if_absent "$HERE/vault-template/_session_logs/_session_template.md" "$AI_ME
 
 # --- assemble the ~/.zshrc lines ---------------------------------------------
 LINES="export AI_MEM_ROOT=\"$AI_MEM_ROOT\""
-if [ "$AI_MEM_AGENTS" != "claude codex gemini cursor" ]; then
+if [ "$AI_MEM_AGENTS" != "claude codex gemini cursor opencode" ]; then
   LINES="$LINES
 export AI_MEM_AGENTS=\"$AI_MEM_AGENTS\""
 fi
@@ -115,10 +118,21 @@ $(printf '%s\n' "$LINES" | sed 's/^/    /')
 EOF
 fi
 
+case "${SHELL:-}" in
+  *zsh) : ;;
+  *) echo; echo "  note: ai-memory is zsh-only; your login shell looks like ${SHELL:-unknown}." ;;
+esac
+
 cat <<EOF
 
-  Done. From inside any git repo, run:  claude-start
-  (or codex-start / gemini-start / cursor-start)
+  Done.
+    tool:  $HERE
+           (keep this folder; your shell sources it on startup)
+    vault: $AI_MEM_ROOT
+           (your memory; safe to back up, sync, or open in Obsidian)
+
+  From inside any git repo, run:  claude-start
+  (or codex-start / gemini-start / cursor-start / opencode-start)
 
   Optional integrations: see $HERE/hooks/  and the README.
 EOF

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ai-memory",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Persistent, agent-agnostic session memory for AI coding CLIs (Claude Code, Codex, Gemini, Cursor, opencode). One Markdown vault, any agent.",
   "bin": {
     "create-ai-memory": "bin/create-ai-memory.js"

package/shell/ai-mem.zsh

@@ -1,7 +1,7 @@
 # === AI CLI + Obsidian memory ===
 # Portable, agent-agnostic session memory. Source this from ~/.zshrc after
 # exporting AI_MEM_ROOT to point at your vault. Zsh-only (uses print -r, ${(s)},
-# select). Add a new agent by defining _ai_adapter_<name> in adapters.zsh and
+# and associative arrays). Add a new agent by defining _ai_adapter_<name> in adapters.zsh and
 # listing it in AI_MEM_AGENTS; a matching <name>-start function is generated.
 
 # Directory holding this module, used to source sibling files.
@@ -350,6 +350,14 @@ _ai_session_start() {
 
     local session_prompt="${*:-}"
 
+    # Fail fast with a clear message if the agent's CLI is missing, before a
+    # session log is created. Cursor is exempt: its adapter falls back to opening
+    # the app when the `cursor` CLI is absent.
+    if [[ "$launcher" != cursor ]] && ! command -v "$launcher" >/dev/null 2>&1; then
+        echo "ai-memory: '$launcher' CLI not found on PATH. Install it, or drop it from AI_MEM_AGENTS." >&2
+        return 1
+    fi
+
     local resolved
     resolved="$(_ai_mem_prepare_session)" || return 1