Remember & edit

Documentation Index

Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

What this means in practice

• remembering a new fact or lesson manually
• saving a checkpoint to mark a session milestone
• editing an existing memory to refine or correct it
• archiving or forgetting a memory to clean up

​

crystal_remember — Save a memory

​

Parameters

​

Valid enum values from schema

​

Returns

{
  "memoryId": "mem_abc123",
  "title": "Chose Convex over Supabase",
  "store": "semantic",
  "obsidianPath": "/Users/user/vault/Memories/semantic/decisions/convex.md"
}

​

Examples

{
  "store": "semantic",
  "category": "decision",
  "title": "Chose PostgreSQL over SQLite for session storage",
  "content": "PostgreSQL supports concurrent writes and ACID transactions needed for multi-user sessions. SQLite would cause lock contention under load.",
  "tags": ["database", "architecture"],
  "confidence": 0.95
}

{
  "store": "semantic",
  "category": "lesson",
  "title": "Mutations preferred over HTTP actions in Convex",
  "content": "Convex mutations are transactional and automatically retried on failure. HTTP actions lack these guarantees and should only be used for external integrations.",
  "tags": ["convex", "reliability"],
  "confidence": 0.9,
  "valence": 0.7,
  "arousal": 0.4
}

{
  "store": "procedural",
  "category": "workflow",
  "title": "Deploy to Railway via git push",
  "content": "1. Make changes locally\n2. Commit and push to main\n3. Railway automatically deploys from the push\n4. Monitor deployment status in Railway dashboard",
  "tags": ["deployment", "railway"],
  "confidence": 0.85
}

{
  "store": "prospective",
  "category": "goal",
  "title": "Complete Knowledge Graph expansion",
  "content": "Implement crystalNodes, crystalRelations, and related indices to enable entity-based memory retrieval and relationship tracking.",
  "tags": ["project", "memory-crystal"],
  "confidence": 0.8
}

{
  "store": "semantic",
  "category": "person",
  "title": "Alice — Product lead",
  "content": "Alice is the product lead for the mobile team. Prefers async communication. Timezone: Pacific.",
  "tags": ["team", "alice"],
  "confidence": 0.9,
  "channel": "product-team"
}

​

Tagging best practices

• Use lowercase, hyphen-separated tags (e.g., backend-architecture, not BackendArchitecture)
• Keep tags concise and reusable across memories
• Avoid redundant tags (don’t tag with both architecture and architectural-decision)
• Use 2–5 tags per memory for good searchability without noise
• Group related topics under a common tag prefix (e.g., convex-*, deploy-*)

​

When to use vs alternatives

​

Error handling

​

How it actually works

• mcp-server/src/tools/remember.ts — tool definition and input validation
• convex/crystal/memories.ts — memory creation, embedding, and storage logic
• convex/crystal/mcp.ts — HTTP endpoint routing
• mcp-server/src/lib/obsidian.ts — Obsidian vault integration

1. Tool validates all input parameters against the schema and enums
2. ConvexClient POSTs to /api/mcp/capture
3. Backend embeds the content using OpenAI’s text-embedding-3-small
4. Memory is stored in the crystalMemories table with vector index
5. If OBSIDIAN_VAULT_PATH is set, memory is also exported as markdown
6. Tool returns the memory ID and Obsidian path (if applicable)

​

Common mistakes

• Assuming manual crystal_remember and automatic crystal_capture are the same path (they’re not — one is explicit, one is automatic)
• Forgetting that checkpoints are a distinct concept from ordinary memories (checkpoints are milestones; memories are facts/lessons)
• Not setting confidence and valence — the defaults are reasonable, but explicit values help the system prioritize
• Using vague titles (❌ “decision”) instead of specific ones (✅ “Chose Convex over Supabase”)
• Storing multiple unrelated facts in one memory instead of breaking them into separate memories

​

Source of truth

• mcp-server/src/tools/remember.ts — tool definition
• convex/crystal/memories.ts — backend logic
• convex/schema.ts — valid enum values
• convex/crystal/mcp.ts
• convex/crystal/checkpoints.ts

​

Notes

​

Shared-mode agent scoping (new in 0.7.15)