diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0c64aba..9356d42 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -12,7 +12,7 @@ "name": "claude-code", "source": "./plugins/claude-code", "description": "Persistent semantic memory for Claude Code — user preferences, project context, prior decisions, and codebase facts that survive across sessions.", - "version": "0.1.11", + "version": "0.1.12", "category": "productivity", "homepage": "https://docs.atomicmemory.ai/integrations/coding-agents/claude-code", "license": "Apache-2.0" diff --git a/README.md b/README.md index 895dca9..9f03b43 100644 --- a/README.md +++ b/README.md @@ -117,23 +117,19 @@ hook and MCP configuration. ### 1. Rebuild after source changes -Build the SDK first if it changed, then rebuild this repo: +The agent plugins published from this repo (Claude Code, Codex, Cursor, etc.) spawn `@atomicmemory/mcp-server` from the npm registry via `npx`, so end users do not need to clone or build this repo to use the plugins. + +When working *on* the integrations repo itself, rebuild changed packages locally: ```bash cd ../atomicmemory-sdk -pnpm build +pnpm build # only if the SDK changed cd ../atomicmemory-integrations -pnpm --filter @atomicmemory/mcp-server build pnpm build ``` -`ATOMICMEMORY_MCP_SERVER_BIN` must point at the rebuilt file: - -```bash -export ATOMICMEMORY_MCP_SERVER_BIN="/absolute/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js" -test -f "$ATOMICMEMORY_MCP_SERVER_BIN" -``` +To make a host agent use your local MCP server checkout instead of the published npm version, override the plugin manifest's `mcpServers.atomicmemory.command`/`args` in a private settings file — for example, point them at `node` + `packages/mcp-server/dist/bin.js`. Do not edit the published manifests in `plugins/*/` for this; the npm-based config is what ships to users. ### Version bump helper @@ -239,7 +235,7 @@ Run `pnpm bump:plugin-versions ` when `.codex-plugin/pl The Codex marketplace entry does not carry a plugin version; the plugin manifest and skill metadata are the source of truth. -Restart Codex or reinstall the local plugin from the repo/personal marketplace so it reloads `.codex-mcp.json` and `SKILL.md`. Verify `ATOMICMEMORY_MCP_SERVER_BIN`, `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, `ATOMICMEMORY_PROVIDER`, and at least one `ATOMICMEMORY_SCOPE_*` env var are visible to Codex. +Restart Codex or reinstall the local plugin from the repo/personal marketplace so it reloads `.codex-mcp.json` and `SKILL.md`. Verify `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, `ATOMICMEMORY_PROVIDER`, and at least one `ATOMICMEMORY_SCOPE_*` env var are visible to Codex. The MCP server itself is fetched from npm via `npx`, so no local bin path is required. ### 4. OpenClaw diff --git a/plugins/claude-code/.claude-plugin/plugin.json b/plugins/claude-code/.claude-plugin/plugin.json index 81eaab5..2284170 100644 --- a/plugins/claude-code/.claude-plugin/plugin.json +++ b/plugins/claude-code/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "atomicmemory", - "version": "0.1.11", + "version": "0.1.12", "description": "Persistent semantic memory for Claude Code — user preferences, project context, prior decisions, and codebase facts that survive across sessions.", "author": { "name": "AtomicMemory", @@ -10,10 +10,9 @@ "license": "Apache-2.0", "mcpServers": { "atomicmemory": { - "command": "bash", - "args": ["-c", "exec node \"$ATOMICMEMORY_MCP_SERVER_BIN\""], + "command": "npx", + "args": ["-y", "--package=@atomicmemory/mcp-server@^0.1.1", "atomicmemory-mcp"], "env": { - "ATOMICMEMORY_MCP_SERVER_BIN": "${ATOMICMEMORY_MCP_SERVER_BIN}", "ATOMICMEMORY_API_URL": "${ATOMICMEMORY_API_URL}", "ATOMICMEMORY_API_KEY": "${ATOMICMEMORY_API_KEY}", "ATOMICMEMORY_PROVIDER": "${ATOMICMEMORY_PROVIDER:-atomicmemory}", diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.md index d4adb88..be62b81 100644 --- a/plugins/claude-code/README.md +++ b/plugins/claude-code/README.md @@ -16,34 +16,11 @@ brew install jq sudo apt-get install -y jq ``` -### 2. Clone and build the MCP server +### 2. Export shell env vars -Clone `atomicmemory-sdk` and `atomicmemory-integrations` side-by-side, then build each in order. The MCP server resolves the SDK through a sibling `file:` spec, and imports from the SDK's `dist/` output — so both repos must exist as siblings and the SDK must be built first. +The MCP server and the lifecycle hook scripts read their config from the shell environment. Export these in `~/.zshrc` / `~/.bashrc` before launching Claude Code: ```bash -# From the parent directory that will hold both repos -git clone https://github.com/atomicstrata/atomicmemory-sdk.git -git clone https://github.com/atomicstrata/atomicmemory-integrations.git - -# Build the SDK (produces atomicmemory-sdk/dist/) -cd atomicmemory-sdk -pnpm install -pnpm build - -# Build the MCP server (produces atomicmemory-integrations/packages/mcp-server/dist/bin.js) -cd ../atomicmemory-integrations -pnpm install -pnpm --filter @atomicmemory/mcp-server build -``` - -### 3. Export shell env vars - -Both the MCP server and the lifecycle hook scripts read their config from the shell environment. Export these in `~/.zshrc` / `~/.bashrc` before launching Claude Code: - -```bash -# Absolute path to the binary built in step 2 -export ATOMICMEMORY_MCP_SERVER_BIN="$HOME/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js" - export ATOMICMEMORY_API_URL="https://memory.yourco.com" export ATOMICMEMORY_API_KEY="am_live_…" export ATOMICMEMORY_PROVIDER="atomicmemory" @@ -55,7 +32,7 @@ export ATOMICMEMORY_CAPTURE_LEVEL="balanced" # minimal|balanced|full # export ATOMICMEMORY_SCOPE_THREAD="" ``` -`ATOMICMEMORY_MCP_SERVER_BIN`, `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, `ATOMICMEMORY_PROVIDER`, `ATOMICMEMORY_SCOPE_USER`, and `ATOMICMEMORY_CAPTURE_LEVEL` are required for the Claude Code plugin and hooks. Optional scope vars narrow retrieval and lifecycle record metadata. +`ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, `ATOMICMEMORY_PROVIDER`, `ATOMICMEMORY_SCOPE_USER`, and `ATOMICMEMORY_CAPTURE_LEVEL` are required for the Claude Code plugin and hooks. Optional scope vars narrow retrieval and lifecycle record metadata. If `ATOMICMEMORY_SCOPE_USER` is empty, the MCP server derives a local user from the host OS; set it explicitly when multiple operators share a machine or when you need a stable cross-machine identity. #### Local extraction with Claude Code auth @@ -77,7 +54,6 @@ for hosted/team deployments where a server would run under one operator's Claude Code subscription. Embeddings still use core's configured embedding provider; select a local embedding provider separately for a fully local setup. -- `_MCP_SERVER_BIN` — absolute path to the built MCP server entry. The plugin spawns it directly, so no npm registry lookup happens. - `_API_URL` / `_API_KEY` / `_PROVIDER` / `_SCOPE_USER` — needed by **both** the MCP server (for `memory_search` / `memory_ingest` / `memory_package` tool calls) and lifecycle hooks. - `_CAPTURE_LEVEL` — controls lifecycle write volume. Valid values are `minimal`, `balanced`, and `full`. - `_SCOPE_NAMESPACE` — used by both, as a per-project isolation boundary. @@ -99,7 +75,7 @@ Optional capture controls: If required config is missing, helper tools are unavailable, or numeric/boolean env vars are invalid, hooks surface the error instead of running in a degraded mode. -### 4. Install the plugin +### 3. Install the plugin From the cloned repo: @@ -111,7 +87,7 @@ claude plugin marketplace add ./ claude plugin install claude-code@atomicmemory ``` -### 5. Update and verify an existing install +### 4. Update and verify an existing install Claude Code updates are version-gated. If hook scripts, `hooks.json`, `.claude-plugin/plugin.json`, skills, or marketplace metadata changed, bump plugin versions from the repo root before relying on `claude plugin update`: @@ -127,11 +103,9 @@ For Claude, the helper keeps these files in sync: If the version stays unchanged, `claude plugin update claude-code@atomicmemory` can report "already at the latest version" while the installed cache still contains older files. -After changing this repo, rebuild the MCP server and refresh Claude's installed plugin cache: +After changing this repo, refresh Claude's installed plugin cache: ```bash -pnpm --filter @atomicmemory/mcp-server build - claude plugin marketplace list # If the plugin is already installed: @@ -141,6 +115,8 @@ claude plugin update claude-code@atomicmemory claude plugin install claude-code@atomicmemory ``` +The plugin spawns `@atomicmemory/mcp-server` from the npm registry via `npx`, so no local build is needed. If you're developing the MCP server itself and want Claude Code to load a local checkout instead, override the manifest's `mcpServers.atomicmemory.command`/`args` in a private settings file rather than editing the published manifest. + If `claude plugin marketplace list` shows `atomicmemory` pointing at an old checkout, replace the marketplace entry from this repo first: ```bash @@ -191,7 +167,7 @@ plugins/claude-code/ └── README.md ``` -The plugin spawns [`@atomicmemory/mcp-server`](../../packages/mcp-server) by `node`-executing the local `dist/bin.js` pointed to by `$ATOMICMEMORY_MCP_SERVER_BIN` — no npm registry lookup. Most semantic memory operations go through the MCP tools. Latency-sensitive prompt retrieval uses `/v1/memories/search/fast` directly, and lifecycle scripts write deterministic records to `/v1/memories/ingest/quick` with `skip_extraction=true` because command hooks cannot talk to Claude Code's already-running stdio MCP child. Hook record content stays clean and human-readable; lifecycle provenance, scope, dedupe keys, session IDs, cwd, transcript paths, tool counts, and validation details are sent separately in request `metadata` and persisted to the memory's `metadata` JSONB column, with `sourceSite` / `sourceUrl` continuing to carry the provider/route identity. +The plugin spawns [`@atomicmemory/mcp-server`](../../packages/mcp-server) from the npm registry via `npx -y --package=@atomicmemory/mcp-server@^0.1.1 atomicmemory-mcp`, so a `claude plugin install` is self-contained — no local clone or build required. Most semantic memory operations go through the MCP tools. Latency-sensitive prompt retrieval uses `/v1/memories/search/fast` directly, and lifecycle scripts write deterministic records to `/v1/memories/ingest/quick` with `skip_extraction=true` because command hooks cannot talk to Claude Code's already-running stdio MCP child. Hook record content stays clean and human-readable; lifecycle provenance, scope, dedupe keys, session IDs, cwd, transcript paths, tool counts, and validation details are sent separately in request `metadata` and persisted to the memory's `metadata` JSONB column, with `sourceSite` / `sourceUrl` continuing to carry the provider/route identity. ## Lifecycle hooks diff --git a/plugins/claude-code/package.json b/plugins/claude-code/package.json index 1f79f45..0df8183 100644 --- a/plugins/claude-code/package.json +++ b/plugins/claude-code/package.json @@ -1,6 +1,6 @@ { "name": "@atomicmemory/claude-code-plugin", - "version": "0.1.11", + "version": "0.1.12", "description": "AtomicMemory plugin for Claude Code — persistent semantic memory across sessions.", "private": false, "license": "Apache-2.0", diff --git a/plugins/codex/.codex-mcp.json b/plugins/codex/.codex-mcp.json index 1d3ae64..b5d852d 100644 --- a/plugins/codex/.codex-mcp.json +++ b/plugins/codex/.codex-mcp.json @@ -1,10 +1,9 @@ { "mcpServers": { "atomicmemory": { - "command": "bash", - "args": ["-c", "exec node \"$ATOMICMEMORY_MCP_SERVER_BIN\""], + "command": "npx", + "args": ["-y", "--package=@atomicmemory/mcp-server@^0.1.1", "atomicmemory-mcp"], "env_vars": [ - "ATOMICMEMORY_MCP_SERVER_BIN", "ATOMICMEMORY_API_URL", "ATOMICMEMORY_API_KEY", "ATOMICMEMORY_PROVIDER", diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json index 916b8c6..6c14c60 100644 --- a/plugins/codex/.codex-plugin/plugin.json +++ b/plugins/codex/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "atomicmemory", - "version": "0.1.11", + "version": "0.1.12", "description": "AtomicMemory memory layer for Codex. Pluggable semantic memory — swap backends through the SDK's MemoryProvider model by config, not code change.", "author": { "name": "AtomicMemory", diff --git a/plugins/codex/README.md b/plugins/codex/README.md index 11276e8..3556368 100644 --- a/plugins/codex/README.md +++ b/plugins/codex/README.md @@ -56,28 +56,9 @@ The MCP config forwards the required environment variables with `env_vars`, so v ## Configure -Before any of the install options, clone `atomicmemory-sdk` and `atomicmemory-integrations` side-by-side, then build each in order. The MCP server resolves the SDK through a sibling `file:` spec and imports from the SDK's `dist/` output, so both repos must exist as siblings and the SDK must be built first. +Export scope and credentials in your shell: ```bash -# From the parent directory that will hold both repos -git clone https://github.com/atomicstrata/atomicmemory-sdk.git -git clone https://github.com/atomicstrata/atomicmemory-integrations.git - -# Build the SDK (produces atomicmemory-sdk/dist/) -cd atomicmemory-sdk -pnpm install -pnpm build - -# Build the MCP server (produces atomicmemory-integrations/packages/mcp-server/dist/bin.js) -cd ../atomicmemory-integrations -pnpm install -pnpm --filter @atomicmemory/mcp-server build -``` - -Then export scope, credentials, and the absolute path to the built binary in your shell: - -```bash -export ATOMICMEMORY_MCP_SERVER_BIN="$HOME/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js" export ATOMICMEMORY_API_URL="https://memory.yourco.com" export ATOMICMEMORY_API_KEY="am_live_…" export ATOMICMEMORY_PROVIDER="atomicmemory" @@ -88,7 +69,7 @@ export ATOMICMEMORY_SCOPE_USER="pip" # export ATOMICMEMORY_SCOPE_THREAD="" ``` -`ATOMICMEMORY_MCP_SERVER_BIN` is required — the plugin spawns the server by `node`-executing that path. At least one `ATOMICMEMORY_SCOPE_*` must also be set — the server rejects scopeless requests. +At least one `ATOMICMEMORY_SCOPE_*` must be set — the server rejects scopeless requests. The MCP server itself is fetched from npm on first use via `npx -y --package=@atomicmemory/mcp-server@^0.1.1 atomicmemory-mcp`, so no local clone or build is required. ## Memory behavior @@ -165,9 +146,9 @@ For Codex, the helper keeps these versions aligned: The marketplace JSON intentionally has no plugin version field. Restart Codex or reinstall the local plugin after changing any of these files so the installed plugin cache reloads the manifest and skill. -## Status: source-only +## Status: plugin source-only, MCP server on npm -Nothing here is published to npm or to any public plugin marketplace. The plugin is installed from a local clone of this repo (Option A / B above), and the MCP server it spawns runs from the local `dist/bin.js` produced by `pnpm --filter @atomicmemory/mcp-server build`. See the [mcp-server status note](../../packages/mcp-server/README.md) for why this is source-only by design. +The Codex *plugin* (manifest + skill) is not yet published to any public Codex plugin marketplace — install it from a local clone of this repo via Option A / B above, or wire `.codex-mcp.json` into Codex directly via Option C. The MCP server it spawns is published as [`@atomicmemory/mcp-server`](https://www.npmjs.com/package/@atomicmemory/mcp-server) and is fetched on first use via `npx`, so no local clone or build of the integrations repo is required to actually run the server. ## License diff --git a/plugins/codex/package.json b/plugins/codex/package.json index 11da0f6..3fc736b 100644 --- a/plugins/codex/package.json +++ b/plugins/codex/package.json @@ -1,6 +1,6 @@ { "name": "@atomicmemory/codex-plugin", - "version": "0.1.11", + "version": "0.1.12", "description": "AtomicMemory plugin for OpenAI Codex — plugin manifest, MCP server config, and memory protocol skill.", "private": true, "license": "Apache-2.0", diff --git a/plugins/codex/skills/atomicmemory/SKILL.md b/plugins/codex/skills/atomicmemory/SKILL.md index a5d8ed1..492b3eb 100644 --- a/plugins/codex/skills/atomicmemory/SKILL.md +++ b/plugins/codex/skills/atomicmemory/SKILL.md @@ -10,7 +10,7 @@ description: > license: Apache-2.0 metadata: author: AtomicMemory - version: "0.1.11" + version: "0.1.12" category: ai-memory tags: "memory, semantic-search, codex, pluggable" --- diff --git a/plugins/cursor/package.json b/plugins/cursor/package.json index a9d9cbb..67fe694 100644 --- a/plugins/cursor/package.json +++ b/plugins/cursor/package.json @@ -1,6 +1,6 @@ { "name": "@atomicmemory/cursor-plugin", - "version": "0.1.11", + "version": "0.1.12", "description": "AtomicMemory integration for Cursor - MCP configuration and project rules for persistent semantic memory.", "private": true, "license": "Apache-2.0", diff --git a/plugins/hermes/plugin.yaml b/plugins/hermes/plugin.yaml index 882fde9..3d81e98 100644 --- a/plugins/hermes/plugin.yaml +++ b/plugins/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: atomicmemory -version: 0.1.11 +version: 0.1.12 description: "AtomicMemory native Hermes memory provider — Python SDK-backed, cross-tool memory by default." pip_dependencies: - "atomicmemory>=1.0.1,<2.0.0" diff --git a/plugins/hermes/pyproject.toml b/plugins/hermes/pyproject.toml index 38bfe31..d8c529d 100644 --- a/plugins/hermes/pyproject.toml +++ b/plugins/hermes/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "atomicmemory-hermes" -version = "0.1.11" +version = "0.1.12" description = "AtomicMemory native Hermes memory provider." readme = "README.md" requires-python = ">=3.10" diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json index 235d27c..2f06dfe 100644 --- a/plugins/openclaw/openclaw.plugin.json +++ b/plugins/openclaw/openclaw.plugin.json @@ -1,7 +1,7 @@ { "id": "atomicmemory", "name": "AtomicMemory", - "version": "0.1.11", + "version": "0.1.12", "description": "Persistent semantic memory for OpenClaw agents — cross-channel user memory and deterministic session snapshots via the AtomicMemory SDK's pluggable MemoryProvider model.", "kind": "memory", "skills": ["./skills/atomicmemory"], diff --git a/plugins/openclaw/package.json b/plugins/openclaw/package.json index 3350ad0..42a9f6f 100644 --- a/plugins/openclaw/package.json +++ b/plugins/openclaw/package.json @@ -1,6 +1,6 @@ { "name": "@atomicmemory/openclaw-plugin", - "version": "0.1.11", + "version": "0.1.12", "description": "AtomicMemory plugin for OpenClaw — persistent semantic memory and deterministic session snapshots across channels.", "type": "module", "main": "dist/index.js", diff --git a/plugins/openclaw/skills/atomicmemory/skill.yaml b/plugins/openclaw/skills/atomicmemory/skill.yaml index 430eaee..d4714a6 100644 --- a/plugins/openclaw/skills/atomicmemory/skill.yaml +++ b/plugins/openclaw/skills/atomicmemory/skill.yaml @@ -1,5 +1,5 @@ name: atomicmemory -version: 0.1.11 +version: 0.1.12 author: name: AtomicMemory url: https://atomicmem.ai