@pinkpixel/memi 0.0.0-stage → 0.1.0

package/skills/memi-setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: memi-setup
+version: 1.0.0
+description: |
+  Install, configure, and troubleshoot memi, the local memory system for AI
+  agents. Use when the user wants to set up memi, connect its MCP server to a
+  client, choose or switch between Ollama and OpenAI embeddings, install the memi
+  skills, back up the database, or when memi reports problems such as
+  "Could not reach", "not found, try pulling it first", "OPENAI_API_KEY is not
+  set", "The embedder changed", "No project detected", or memories missing
+  vectors. Also use to interpret `memi doctor` output.
+license: Apache-2.0
+compatibility: claude-code cursor codex gemini-cli opencode
+---
+
+# Setting up memi
+
+Start with `memi doctor`. It checks the database, the embedder, the vector index, and project detection, and exits 1 if something is wrong. Most problems show up there with a line that says what to do.
+
+## Requirements
+
+- Node.js 22 or newer.
+- One embedder:
+  - **Ollama** (the default, runs locally): install Ollama, then `ollama pull nomic-embed-text`.
+  - **OpenAI**: an API key in the `OPENAI_API_KEY` environment variable. Memory text is sent to OpenAI to be embedded.
+
+## Install
+
+memi is not published to npm yet, so build it from source:
+
+```bash
+npm install
+npm run build
+node dist/cli/index.js doctor
+```
+
+Use the absolute path to `dist/cli/index.js` wherever a command below says `<memi>`. Once `@pinkpixel/memi` is published, `npx -y @pinkpixel/memi` will replace `node <path>`.
+
+## Connect the MCP server
+
+### Claude Code
+
+```bash
+claude mcp add memi -s user -e MEMI_AGENT=claude -- node /absolute/path/to/memi/dist/cli/index.js serve
+claude mcp list
+```
+
+`-s user` makes memi available in every project, which is what you want because memory is shared across them. Drop it to limit memi to the current project. `MEMI_AGENT` is optional, see "Agent name" below.
+
+### Other clients
+
+Any client that can launch a stdio MCP server needs the same three things: a command, its arguments, and optional environment variables. In the common `mcpServers` JSON format:
+
+```json
+{
+  "mcpServers": {
+    "memi": {
+      "command": "node",
+      "args": ["/absolute/path/to/memi/dist/cli/index.js", "serve"],
+      "env": { "MEMI_AGENT": "my-agent" }
+    }
+  }
+}
+```
+
+Use an absolute path. Restart the client after editing its config. memi has been tested with Claude Code. Other clients should work but have not been checked.
+
+## Install the skills
+
+Copy the folders in `skills/` (`memi-memory`, `memi-curate`, `memi-setup`) into your client's skills directory. For Claude Code that is `~/.claude/skills/`. Symlinks work too, so updates to the repo carry through.
+
+## Agent name
+
+Memories are tied to a project, which memi works out from the git repo folder name. In a folder with no git repo it falls back to the agent name, stored as `agent:<name>`. Without either, project memories cannot be saved.
+
+Set the name with `memi config set agent <name>` or the `MEMI_AGENT` environment variable. `MEMI_PROJECT` forces a project name outright.
+
+The agent name is also recorded on each memory so you can see who wrote it.
+
+## Embedders
+
+```bash
+memi config                                         # show what is in effect
+memi config set embedder.provider openai            # ollama or openai
+memi config set embedder.model text-embedding-3-small
+memi config set embedder.baseUrl http://localhost:11434
+```
+
+| Provider | Default model | Needs |
+|---|---|---|
+| `ollama` | `nomic-embed-text` | Ollama running, the model pulled |
+| `openai` | `text-embedding-3-small` | `OPENAI_API_KEY` in the environment that launches memi |
+
+The API key is only ever read from the environment. memi never writes it to `config.json`. For an MCP client, put it in the server's `env` block (for Claude Code, add `-e OPENAI_API_KEY=...` to the `claude mcp add` command).
+
+Environment variables override the config file: `MEMI_EMBED_PROVIDER`, `MEMI_EMBED_MODEL`, `MEMI_OLLAMA_URL`, `OPENAI_BASE_URL`.
+
+### Switching embedders
+
+> **Different models produce vectors with different dimensions, so existing vectors cannot be reused.**
+
+When you change the provider or model, memi notices that the stored vectors came from something else. Semantic search turns off and keyword search carries on. Nothing is deleted. To finish the switch:
+
+```bash
+memi reindex
+```
+
+This drops the vector table, rebuilds it for the new model, and re-embeds every saved memory. **Your memories are kept.** It asks for confirmation (pass `--yes` in scripts). All the embedding happens before anything is dropped, so if the new embedder is unreachable, nothing changes. With OpenAI, reindexing sends every memory's text to OpenAI.
+
+If you switch back to the model the vectors were built with, no reindex is needed.
+
+## Where the data lives
+
+- Database: `~/.memi/memi.db`. Config: `~/.memi/config.json`. Set `MEMI_HOME` to move both.
+- SQLite runs in WAL mode, so you may see `memi.db-wal` and `memi.db-shm` next to the database while memi is running.
+- To back up, copy the three files together while nothing is using the database, or use `sqlite3 ~/.memi/memi.db ".backup backup.db"`.
+- Restoring the database brings back the memories and their vectors. If you restore it while using a different embedder, memi will ask for a reindex.
+
+## Reading `memi doctor`
+
+| Line | Meaning | Fix |
+|---|---|---|
+| `fail Could not reach http://localhost:11434...` | Ollama is not running | Start Ollama |
+| `fail ... model "x" not found, try pulling it first` | The model is not downloaded | `ollama pull x` |
+| `fail OPENAI_API_KEY is not set` | Provider is `openai` with no key | Export the key where memi runs |
+| `fail The embedder changed from ...` | Config no longer matches the stored vectors | `memi reindex`, or switch the config back |
+| `warn N memories have no vector` | Saved while the embedder was down | `memi reindex --missing` (drops nothing) |
+| `warn No project detected here` | No git repo, and no agent name | Set `MEMI_AGENT`, or run inside a git repo |
+| `ok No vectors yet` | Nothing saved yet | Nothing. The index is created on the first save |
+
+## The local UI
+
+`memi ui` starts a memory manager at `http://localhost:4747`. Use it to browse, search, edit, pin, and delete memories. Add `--open` to open your browser, or `--port <n>` to change the port (or `memi config set ui.port <n>`). Press Ctrl+C to stop it.
+
+It only listens on this machine and ignores requests that don't come from `localhost`. If it says the port is already in use, something else is on 4747 (often another `memi ui`), so pick another port.
+
+If the UI shows a banner about the embedder, it is the same message as `memi doctor`. The UI doesn't run `memi reindex` for you, but the banner has the command with a copy button.
+
+## If the MCP client shows no memi tools
+
+1. Run `memi doctor` outside the client to rule out memi itself.
+2. Check the path in the client config is absolute and that `npm run build` has been run.
+3. Make sure the environment the client launches in can see `node`.
+4. Restart the client.

package/ui/css/controls.css

@@ -0,0 +1,274 @@
+/* Buttons */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: var(--control);
+  padding: 0 14px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius);
+  background: transparent;
+  font-weight: 500;
+  white-space: nowrap;
+  transition: background-color 120ms var(--ease), border-color 120ms var(--ease), opacity 120ms var(--ease);
+}
+
+.btn:hover {
+  background: var(--surface-2);
+}
+
+.btn:active {
+  background: var(--border);
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-primary {
+  background: var(--text);
+  border-color: var(--text);
+  color: var(--bg);
+}
+
+.btn-primary:hover {
+  background: oklch(0.88 0.004 265);
+  border-color: oklch(0.88 0.004 265);
+}
+
+.btn-primary:active {
+  background: oklch(0.8 0.005 265);
+}
+
+.btn-danger {
+  border-color: var(--danger);
+  color: var(--danger);
+}
+
+.btn-danger:hover {
+  background: var(--danger-surface);
+}
+
+.btn-danger.solid {
+  background: var(--danger);
+  color: var(--bg);
+}
+
+.btn-danger.solid:hover {
+  background: oklch(0.76 0.16 25);
+}
+
+.btn-icon {
+  width: var(--control);
+  padding: 0;
+  border-color: transparent;
+  color: var(--text-dim);
+}
+
+.btn-icon:hover {
+  color: var(--text);
+}
+
+.btn-icon[aria-pressed="true"] {
+  color: var(--accent);
+}
+
+.btn-icon.danger:hover {
+  color: var(--danger);
+  background: var(--danger-surface);
+}
+
+.btn.loading {
+  opacity: 0.7;
+  pointer-events: none;
+}
+
+/* Inputs */
+.input,
+.select,
+.textarea {
+  width: 100%;
+  min-height: var(--control);
+  padding: 0 12px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius);
+  background: var(--bg);
+  transition: border-color 120ms var(--ease);
+}
+
+.input:hover,
+.select:hover,
+.textarea:hover {
+  border-color: var(--text-faint);
+}
+
+.input::placeholder,
+.textarea::placeholder {
+  color: var(--text-faint);
+}
+
+.textarea {
+  padding: 10px 12px;
+  line-height: 1.5;
+  resize: vertical;
+  min-height: 140px;
+}
+
+.select {
+  width: auto;
+  padding-right: 8px;
+}
+
+.input[aria-invalid="true"],
+.textarea[aria-invalid="true"] {
+  border-color: var(--danger);
+}
+
+.search {
+  position: relative;
+  display: flex;
+  align-items: center;
+}
+
+.search > svg {
+  position: absolute;
+  left: 12px;
+  color: var(--text-faint);
+  pointer-events: none;
+}
+
+.search .input {
+  padding-left: 38px;
+  padding-right: var(--control);
+}
+
+/* The page has its own clear button, so hide the browser's. */
+.search .input::-webkit-search-cancel-button {
+  appearance: none;
+}
+
+.search .clear {
+  position: absolute;
+  right: 2px;
+}
+
+/* Segmented control, used for search mode and importance */
+.segmented {
+  display: inline-flex;
+  padding: 2px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--radius);
+  background: var(--bg);
+}
+
+.segmented > * {
+  flex: 1;
+}
+
+.segmented button,
+.segmented label {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: calc(var(--control) - 6px);
+  min-width: 36px;
+  padding: 0 10px;
+  border: 0;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--text-dim);
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  white-space: nowrap;
+  transition: background-color 120ms var(--ease), color 120ms var(--ease);
+}
+
+.segmented button:hover,
+.segmented label:hover {
+  color: var(--text);
+}
+
+.segmented button[aria-pressed="true"],
+.segmented label:has(input:checked) {
+  background: var(--surface-2);
+  color: var(--text);
+}
+
+.segmented input {
+  position: absolute;
+  opacity: 0;
+  pointer-events: none;
+}
+
+.segmented label:has(input:focus-visible) {
+  outline: 2px solid var(--accent);
+  outline-offset: 1px;
+}
+
+/* Sidebar navigation */
+.nav-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  min-height: var(--control);
+  padding: 0 8px;
+  border: 0;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--text-dim);
+  text-align: left;
+  transition: background-color 120ms var(--ease), color 120ms var(--ease);
+}
+
+.nav-item:hover {
+  background: var(--surface-2);
+  color: var(--text);
+}
+
+.nav-item[aria-current="true"] {
+  background: var(--surface-2);
+  color: var(--text);
+  font-weight: 500;
+}
+
+.nav-item .label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.nav-item .count {
+  color: var(--text-faint);
+  font: 400 12px/1 var(--font-mono);
+}
+
+.nav-item .here {
+  padding: 2px 6px;
+  border: 1px solid var(--border-strong);
+  border-radius: 999px;
+  color: var(--text-dim);
+  font-size: 11px;
+}
+
+.check-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-height: var(--control);
+  padding: 0 8px;
+  color: var(--text-dim);
+  cursor: pointer;
+}
+
+.check-row input {
+  width: 18px;
+  height: 18px;
+  margin: 0;
+  accent-color: var(--accent);
+}

package/ui/css/dialogs.css

@@ -0,0 +1,145 @@
+/* Dialogs: the editor is a side sheet on desktop and full screen on phones. */
+dialog {
+  padding: 0;
+  border: 1px solid var(--border-strong);
+  background: var(--surface);
+  color: var(--text);
+}
+
+dialog::backdrop {
+  background: oklch(0.1 0.005 265 / 0.6);
+}
+
+dialog.sheet {
+  width: min(560px, 100%);
+  height: 100dvh;
+  max-width: none;
+  max-height: none;
+  margin: 0 0 0 auto;
+  border-width: 0 0 0 1px;
+  border-radius: 0;
+}
+
+dialog.sheet[open] {
+  display: flex;
+  flex-direction: column;
+  animation: sheet-in 180ms var(--ease);
+}
+
+dialog.modal {
+  width: min(420px, calc(100% - 2 * var(--gutter)));
+  margin: auto;
+  border-radius: var(--radius);
+}
+
+dialog.modal[open] {
+  animation: fade-in 140ms var(--ease);
+}
+
+@keyframes sheet-in {
+  from {
+    opacity: 0;
+    transform: translateX(24px);
+  }
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+}
+
+.dialog-form {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  flex: 1;
+}
+
+.dialog-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 12px var(--gutter);
+  border-bottom: 1px solid var(--border);
+}
+
+.dialog-head h2 {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.dialog-body {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  display: grid;
+  align-content: start;
+  gap: 18px;
+  padding: var(--gutter);
+}
+
+.dialog-foot {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 12px var(--gutter);
+  border-top: 1px solid var(--border);
+}
+
+.dialog-foot .spacer {
+  flex: 1;
+}
+
+.modal .dialog-body {
+  gap: 8px;
+}
+
+.modal p {
+  margin: 0;
+  color: var(--text-dim);
+}
+
+.field {
+  display: grid;
+  gap: 6px;
+}
+
+.field > label,
+.field > .label {
+  color: var(--text-dim);
+  font-size: 13px;
+  font-weight: 500;
+}
+
+.field-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.field-row > .input {
+  flex: 1 1 180px;
+}
+
+.form-error {
+  margin: 0;
+  color: var(--danger);
+  font-size: 14px;
+}
+
+.fine {
+  color: var(--text-faint);
+  font: 400 12px/1.5 var(--font-mono);
+}
+
+@media (max-width: 899px) {
+  dialog.sheet {
+    width: 100%;
+    border-width: 0;
+  }
+}