@audaxic/memory-claude 1.0.4 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,6 +11,7 @@ npx @audaxic/memory-claude install
11
11
  This will:
12
12
  1. Prompt for your Audaxic API key (saved to `~/.config/audaxic/config.json`)
13
13
  2. Copy the plugin to `~/.claude/skills/audaxic-memory/`
14
+ 3. Configure the Audaxic MCP server (`.mcp.json` with your API key)
14
15
 
15
16
  The plugin auto-loads on your next Claude Code session.
16
17
 
@@ -18,30 +19,33 @@ Get your API key from: https://memory-dashboard.audaxic.com
18
19
 
19
20
  ## How It Works
20
21
 
21
- The plugin registers two Claude Code hooks:
22
+ The plugin combines three mechanisms:
22
23
 
23
- ### `UserPromptSubmit` → `inject.js`
24
+ ### Skill → auto-search on questions
24
25
 
25
- When you submit a prompt, this hook:
26
- 1. Buffers your prompt to the plugin data directory
27
- 2. Searches Audaxic Memory for relevant context (`POST /search`)
28
- 3. Injects retrieved memories as `<audaxic_memory_context>` into Claude via `additionalContext`
26
+ An Agent Skill (`skills/audaxic-memory/SKILL.md`) instructs Claude to search Audaxic Memory before answering questions about your past decisions, projects, and preferences — then answer directly from the results.
29
27
 
30
- ### `Stop` → `capture.js`
28
+ ### MCP server → trusted memory tools
31
29
 
32
- When Claude finishes responding, this hook:
33
- 1. Buffers the assistant's response
34
- 2. When the buffer reaches 30 messages, flushes to `POST /add`
35
- 3. Skips captures from automatic continuations (`stop_hook_active`)
30
+ The plugin bundles the Audaxic MCP server (`.mcp.json`), giving Claude `search_memories` / `add_memory` / `get_memories` tools. MCP tool results are trusted by Claude, so memory recall actually reaches the answer.
31
+
32
+ ### Hooks → background saving
33
+
34
+ - `UserPromptSubmit` → `inject.mjs`: saves your prompt immediately and injects context via `additionalContext` (a passive enhancement — injection may be deprioritized by Claude Code, which is why the skill + MCP path exists)
35
+ - `Stop` → `capture.mjs`: saves the assistant's response immediately
36
+
37
+ Saving is crash-safe and parallel-safe: each message is written to its own parking file under `${CLAUDE_PLUGIN_DATA}/pending/` and deleted only after `POST /add` confirms receipt. Failed saves stay parked and are retried automatically (stale files, older than 60s, are claimed atomically). Multiple simultaneous Claude Code sessions never share or overwrite files.
36
38
 
37
39
  ## API Key
38
40
 
39
- The plugin reads your API key in this order:
41
+ The plugin uses your API key in this order:
40
42
 
41
43
  1. `CLAUDE_PLUGIN_OPTION_API_TOKEN` — set via the plugin's `userConfig` prompt during `/plugin install`
42
44
  2. `~/.config/audaxic/config.json` — shared config used by all Audaxic integrations
43
45
 
44
- Both hooks fail silently if no key is found — they never block Claude Code.
46
+ The key is also written into the plugin's `.mcp.json` at install time (mode 0600) so the MCP server authenticates automatically.
47
+
48
+ All scripts fail silently if no key is found — they never block Claude Code.
45
49
 
46
50
  ## Architecture
47
51
 
@@ -52,16 +56,17 @@ Both hooks fail silently if no key is found — they never block Claude Code.
52
56
  │ User types prompt │
53
57
  │ │ │
54
58
  │ ▼ │
55
- │ UserPromptSubmit ──► inject.js │
56
- │ │ ├─ buffer user prompt to disk │
59
+ │ UserPromptSubmit ──► inject.mjs │
60
+ │ │ ├─ park + POST /add (immediate) │
57
61
  │ │ └─ POST /search → additionalContext │
58
62
  │ ▼ │
59
63
  │ Claude responds │
60
64
  │ │ │
61
65
  │ ▼ │
62
- │ Stop ──────────────► capture.js │
63
- │ ├─ buffer assistant msg to disk │
64
- │ └─ if buffer >= 30 → POST /add │
66
+ │ Stop ──────────────► capture.mjs │
67
+ │ └─ park + POST /add (immediate) │
68
+ │ │
69
+ │ pending/ → per-message parking files, retried when stale │
65
70
  └──────────────────────────────────────────────────────────────┘
66
71
  ```
67
72
 
@@ -76,7 +81,7 @@ rm -rf ~/.claude/skills/audaxic-memory
76
81
  | Endpoint | Method | Description |
77
82
  |----------|--------|-------------|
78
83
  | `https://api.memory.audaxic.com/search` | POST | Search memories for context injection |
79
- | `https://api.memory.audaxic.com/add` | POST | Save conversation messages in batch |
84
+ | `https://api.memory.audaxic.com/add` | POST | Save conversation messages |
80
85
 
81
86
  ## Related
82
87
 
package/bin/install.js CHANGED
@@ -143,7 +143,7 @@ async function main() {
143
143
  console.log("Audaxic Memory is now active in Claude Code.");
144
144
  console.log(" • Skill → auto-searches memory for your questions");
145
145
  console.log(" • MCP tools → search_memories / add_memory");
146
- console.log(" • Hooks → buffers messages + auto-flushes at 30");
146
+ console.log(" • Hooks → saves every message immediately (parallel-safe)");
147
147
  console.log("\nThe plugin auto-loads on your next Claude Code session.");
148
148
  console.log("If the API key prompt doesn't appear, the key from");
149
149
  console.log("~/.config/audaxic/config.json will be used automatically.\n");
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@audaxic/memory-claude",
3
- "version": "1.0.4",
3
+ "version": "1.1.0",
4
4
  "description": "Claude Code plugin for Audaxic Memory — automatically saves conversation facts and injects semantic context",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,13 +1,13 @@
1
- import { readFile, writeFile, mkdir } from "node:fs/promises";
1
+ import { readFile } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
  import { homedir } from "node:os";
4
+ import { saveMessage, drainStale, migrateLegacy } from "./parking.mjs";
4
5
 
5
- const API_BASE = "https://api.memory.audaxic.com";
6
6
  const CONFIG_PATH = join(homedir(), ".config", "audaxic", "config.json");
7
7
  const BUFFER_DIR =
8
8
  process.env.CLAUDE_PLUGIN_DATA || join(homedir(), ".claude", "audaxic");
9
- const BUFFER_PATH = join(BUFFER_DIR, "buffer.json");
10
- const BUFFER_FLUSH_SIZE = 30;
9
+ const PENDING_DIR = join(BUFFER_DIR, "pending");
10
+ const LEGACY_BUFFER_PATH = join(BUFFER_DIR, "buffer.json");
11
11
 
12
12
  async function readStdin() {
13
13
  const chunks = [];
@@ -31,42 +31,6 @@ async function loadApiKey() {
31
31
  return null;
32
32
  }
33
33
 
34
- async function readBuffer() {
35
- try {
36
- const raw = await readFile(BUFFER_PATH, "utf-8");
37
- const arr = JSON.parse(raw);
38
- return Array.isArray(arr) ? arr : [];
39
- } catch {
40
- return [];
41
- }
42
- }
43
-
44
- async function writeBuffer(buffer) {
45
- await mkdir(BUFFER_DIR, { recursive: true });
46
- await writeFile(BUFFER_PATH, JSON.stringify(buffer, null, 2), {
47
- mode: 0o600,
48
- });
49
- }
50
-
51
- async function flushToApi(apiKey, messages) {
52
- const timestamp = new Date().toISOString().split("T")[0];
53
-
54
- try {
55
- const response = await fetch(`${API_BASE}/add`, {
56
- method: "POST",
57
- headers: {
58
- "Content-Type": "application/json",
59
- Authorization: `Bearer ${apiKey}`,
60
- },
61
- body: JSON.stringify({ messages, timestamp }),
62
- });
63
-
64
- return response.ok;
65
- } catch {
66
- return false;
67
- }
68
- }
69
-
70
34
  async function main() {
71
35
  try {
72
36
  const input = await readStdin();
@@ -89,15 +53,10 @@ async function main() {
89
53
  process.exit(0);
90
54
  }
91
55
 
92
- const buffer = await readBuffer();
93
- buffer.push(assistantMessage.trim());
56
+ await migrateLegacy(apiKey, LEGACY_BUFFER_PATH, PENDING_DIR);
94
57
 
95
- if (buffer.length >= BUFFER_FLUSH_SIZE) {
96
- const success = await flushToApi(apiKey, buffer);
97
- await writeBuffer(success ? [] : buffer);
98
- } else {
99
- await writeBuffer(buffer);
100
- }
58
+ await saveMessage(apiKey, PENDING_DIR, assistantMessage.trim());
59
+ await drainStale(apiKey, PENDING_DIR);
101
60
 
102
61
  process.exit(0);
103
62
  } catch {
@@ -1,7 +1,8 @@
1
- import { readFile, writeFile, mkdir, appendFile } from "node:fs/promises";
1
+ import { readFile, appendFile, mkdir } from "node:fs/promises";
2
2
  import { join } from "node:path";
3
3
  import { homedir } from "node:os";
4
4
  import { setDefaultResultOrder } from "node:dns";
5
+ import { saveMessage, drainStale, migrateLegacy } from "./parking.mjs";
5
6
 
6
7
  setDefaultResultOrder("ipv4first");
7
8
 
@@ -9,7 +10,8 @@ const API_BASE = "https://api.memory.audaxic.com";
9
10
  const CONFIG_PATH = join(homedir(), ".config", "audaxic", "config.json");
10
11
  const BUFFER_DIR =
11
12
  process.env.CLAUDE_PLUGIN_DATA || join(homedir(), ".claude", "audaxic");
12
- const BUFFER_PATH = join(BUFFER_DIR, "buffer.json");
13
+ const PENDING_DIR = join(BUFFER_DIR, "pending");
14
+ const LEGACY_BUFFER_PATH = join(BUFFER_DIR, "buffer.json");
13
15
  const LOG_PATH = join(BUFFER_DIR, "hook.log");
14
16
  const SEARCH_TIMEOUT_MS = 8000;
15
17
  const SEARCH_ATTEMPTS = 2;
@@ -47,23 +49,6 @@ async function loadApiKey() {
47
49
  return null;
48
50
  }
49
51
 
50
- async function readBuffer() {
51
- try {
52
- const raw = await readFile(BUFFER_PATH, "utf-8");
53
- const arr = JSON.parse(raw);
54
- return Array.isArray(arr) ? arr : [];
55
- } catch {
56
- return [];
57
- }
58
- }
59
-
60
- async function writeBuffer(buffer) {
61
- await mkdir(BUFFER_DIR, { recursive: true });
62
- await writeFile(BUFFER_PATH, JSON.stringify(buffer, null, 2), {
63
- mode: 0o600,
64
- });
65
- }
66
-
67
52
  async function searchOnce(apiKey, query) {
68
53
  const controller = new AbortController();
69
54
  const timeout = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
@@ -104,6 +89,11 @@ async function searchMemory(apiKey, query) {
104
89
  return [];
105
90
  }
106
91
 
92
+ async function saveAndDrain(apiKey, message) {
93
+ await saveMessage(apiKey, PENDING_DIR, message);
94
+ await drainStale(apiKey, PENDING_DIR);
95
+ }
96
+
107
97
  function outputJson(obj) {
108
98
  process.stdout.write(JSON.stringify(obj));
109
99
  }
@@ -124,11 +114,16 @@ async function main() {
124
114
  return;
125
115
  }
126
116
 
127
- const buffer = await readBuffer();
128
- buffer.push(prompt.trim());
129
- await writeBuffer(buffer);
117
+ await migrateLegacy(apiKey, LEGACY_BUFFER_PATH, PENDING_DIR);
118
+
119
+ const [, searchResult] = await Promise.allSettled([
120
+ saveAndDrain(apiKey, prompt.trim()),
121
+ searchMemory(apiKey, prompt.trim()),
122
+ ]);
123
+
124
+ const results =
125
+ searchResult.status === "fulfilled" ? searchResult.value : [];
130
126
 
131
- const results = await searchMemory(apiKey, prompt.trim());
132
127
  if (!results.length) {
133
128
  outputJson({});
134
129
  return;
@@ -0,0 +1,136 @@
1
+ import {
2
+ readFile,
3
+ writeFile,
4
+ mkdir,
5
+ unlink,
6
+ rename,
7
+ readdir,
8
+ stat,
9
+ } from "node:fs/promises";
10
+ import { join } from "node:path";
11
+
12
+ const API_BASE = "https://api.memory.audaxic.com";
13
+ export const SEND_TIMEOUT_MS = 6000;
14
+ export const DRAIN_STALE_MS = 60000;
15
+ export const DRAIN_LIMIT = 2;
16
+
17
+ function today() {
18
+ return new Date().toISOString().split("T")[0];
19
+ }
20
+
21
+ function randomSuffix() {
22
+ return Math.random().toString(36).slice(2, 10);
23
+ }
24
+
25
+ export async function postAdd(apiKey, messages, date) {
26
+ const controller = new AbortController();
27
+ const timeout = setTimeout(() => controller.abort(), SEND_TIMEOUT_MS);
28
+
29
+ try {
30
+ const response = await fetch(`${API_BASE}/add`, {
31
+ method: "POST",
32
+ headers: {
33
+ "Content-Type": "application/json",
34
+ Authorization: `Bearer ${apiKey}`,
35
+ },
36
+ body: JSON.stringify({ messages, timestamp: date || today() }),
37
+ signal: controller.signal,
38
+ });
39
+
40
+ return response.ok;
41
+ } catch {
42
+ return false;
43
+ } finally {
44
+ clearTimeout(timeout);
45
+ }
46
+ }
47
+
48
+ async function sendParked(apiKey, file) {
49
+ let payload;
50
+ try {
51
+ payload = JSON.parse(await readFile(file, "utf-8"));
52
+ } catch {
53
+ await unlink(file).catch(() => {});
54
+ return false;
55
+ }
56
+
57
+ const message =
58
+ typeof payload?.message === "string" ? payload.message.trim() : "";
59
+ if (!message) {
60
+ await unlink(file).catch(() => {});
61
+ return false;
62
+ }
63
+
64
+ const ok = await postAdd(apiKey, [message], payload.date);
65
+ if (ok) await unlink(file).catch(() => {});
66
+ return ok;
67
+ }
68
+
69
+ export async function saveMessage(apiKey, pendingDir, message) {
70
+ const text = typeof message === "string" ? message.trim() : "";
71
+ if (!text) return false;
72
+
73
+ const file = join(pendingDir, `${Date.now()}-${randomSuffix()}.json`);
74
+ try {
75
+ await mkdir(pendingDir, { recursive: true });
76
+ await writeFile(file, JSON.stringify({ message: text, date: today() }), {
77
+ mode: 0o600,
78
+ });
79
+ } catch {
80
+ return false;
81
+ }
82
+
83
+ return sendParked(apiKey, file);
84
+ }
85
+
86
+ export async function drainStale(apiKey, pendingDir, limit = DRAIN_LIMIT) {
87
+ const entries = await readdir(pendingDir).catch(() => []);
88
+
89
+ let drained = 0;
90
+ for (const entry of entries) {
91
+ if (drained >= limit) break;
92
+ if (!entry.endsWith(".json")) continue;
93
+
94
+ const file = join(pendingDir, entry);
95
+ const info = await stat(file).catch(() => null);
96
+ if (!info || Date.now() - info.mtimeMs < DRAIN_STALE_MS) continue;
97
+
98
+ const claim = `${file}.claim-${randomSuffix()}`;
99
+ try {
100
+ await rename(file, claim);
101
+ } catch {
102
+ continue;
103
+ }
104
+
105
+ const ok = await sendParked(apiKey, claim);
106
+ if (!ok) await rename(claim, file).catch(() => {});
107
+ drained++;
108
+ }
109
+ }
110
+
111
+ export async function migrateLegacy(apiKey, legacyPath, pendingDir) {
112
+ try {
113
+ const raw = await readFile(legacyPath, "utf-8");
114
+ const parsed = JSON.parse(raw);
115
+ const messages = Array.isArray(parsed)
116
+ ? parsed.filter((m) => typeof m === "string" && m.trim())
117
+ : [];
118
+
119
+ if (messages.length > 0) {
120
+ const ok = await postAdd(apiKey, messages, today());
121
+ if (!ok) {
122
+ await mkdir(pendingDir, { recursive: true });
123
+ for (const message of messages) {
124
+ const file = join(pendingDir, `${Date.now()}-${randomSuffix()}.json`);
125
+ await writeFile(
126
+ file,
127
+ JSON.stringify({ message, date: today() }),
128
+ { mode: 0o600 }
129
+ );
130
+ }
131
+ }
132
+ }
133
+
134
+ await unlink(legacyPath).catch(() => {});
135
+ } catch {}
136
+ }