memoryClaw: Skill for Claude Code

memory_add Patterns — Akashic Context Sprint 1

What memory_add does

Takes a raw message → extracts structured facts → stores in user's memory. Two paths depending on deduplication check:

memory_add({ message, userId })
  │
  ├─ embed(message)
  ├─ searchVectorInProcess(embedding, limit=3, threshold=0.15 distance)
  │
  ├─ IF similar found (distance ≤ 0.15 = similarity ≥ 0.85):
  │     LLM merge(existing_content + new_message)
  │     → memory_store(existing_path, merged)
  │     → return { action: "merged", path }
  │
  └─ IF no similar found:
        LLM extract(message)
        → memory_store("memory/facts-{TIMESTAMP}.md", extracted)
        → return { action: "created", path }

Decision Log Reference

• D2: Merge (not update/append/skip) — preserves all unique facts AND updates outdated info
• D3: Threshold 0.85 cosine (0.15 distance) — conservative enough to not confuse topics
• D4: Implemented in mcp-server (not core) — LLM calls are server responsibility
• D5: gpt-4o-mini default — cost-effective for fact extraction

Zod Schema

const schema = z.object({
  message: z.string().min(1),
  userId: z.string().optional().default("default"),
});

LLM Prompts

EXTRACT_PROMPT (new memory)

const EXTRACT_PROMPT = (message: string) => `
Extract structured facts from the following message as clean Markdown.
Use headers for categories (e.g. ## Profile, ## Preferences, ## Projects).
Be concise. Only include factual information. Ignore questions or commands.

Message: ${message}
`.trim();

MERGE_PROMPT (deduplication found)

const MERGE_PROMPT = (existing: string, newMessage: string) => `
You have existing memory and new information about the same topic.
Produce a merged Markdown document that:
- Preserves all unique facts from existing memory
- Updates any outdated information with the new version
- Adds any new facts not present in existing memory
- Keeps the same Markdown structure

Existing memory:
${existing}

New information:
${newMessage}
`.trim();