Skip to main content

​
From text to vectors

When you store a memory, MemoClaw converts the text into a 512-dimensional vector using OpenAI’s text-embedding-3-small model. These vectors capture semantic meaning — similar concepts produce similar vectors, even with different wording. For example, “user prefers dark mode” and “they like dark themes” will have vectors that are very close together, even though the words are completely different. When you recall, your query is also converted to a vector. PostgreSQL with pgvector finds the closest stored vectors using cosine distance. The HNSW (Hierarchical Navigable Small World) index makes this fast even with millions of memories.

​
Scoring formula

Hybrid recall scoring (4-signal approach):
hybrid = vector_sim × 0.55 + keyword_match × 0.25 + recency × 0.20
score  = hybrid × context_importance × access_boost × type_decay
Signals:
  • vector_sim: Cosine similarity (0–1) — primary semantic signal
  • keyword_match: Full-text/BM25 match, normalized (0–1) — exact term matches
  • recency: exp(-age_days / 30) — temporal freshness
  • context_importance: Importance dynamically boosted by query relevance
  • access_boost: min(1 + access_count × 0.1, 2.0) — frequently recalled memories rank higher
  • type_decay: Exponential decay based on memory type half-life (correction: 180d, preference: 180d, decision: 90d, project: 30d, observation: 14d, general: 60d). Pinned memories are exempt from decay. Memories with more relations decay slower.
When keyword match is strong (>0.3), its weight increases to 0.35 (vector drops to 0.45) for adaptive boosting.
This means highly important memories surface first when similarity is close, but a low-importance memory with high semantic relevance can still beat a high-importance memory with weak relevance.

​
Embedding cache

MemoClaw maintains an LRU cache of 1,000 embeddings. Repeated text won’t consume additional OpenAI API tokens. Cache hits are instant. This is particularly useful for agents that recall the same queries across sessions — the embedding is computed once and reused.

​
Namespaces

Use namespaces to isolate memories per project or context. The default namespace is "default". Suggested strategy:
Namespace patternUse case
defaultGeneral user info and preferences
project-{name}Project-specific knowledge
session-{date}Session summaries
Namespaces are scoped per user — two different wallets can each have a default namespace without any overlap.

​
Tags and metadata filtering

Attach tags to memories for category-based filtering. Recall supports filtering by tags (match any) and by date (after). Metadata is stored as JSONB and supports:
  • Up to 20 keys per memory
  • Up to 3 levels of nesting
  • Any JSON-compatible values
{
  "tags": ["preference", "editor"],
  "source": "onboarding",
  "context": {
    "project": "memoclaw",
    "session": "2025-01-15"
  }
}

​
When to store

Good candidates for storage:
  • User preferences and settings
  • Important decisions and rationale
  • Context useful in future sessions
  • Project-specific knowledge
  • Lessons learned from corrections

​
When NOT to store

Avoid storing:
  • Passwords, API keys, tokens, or secrets
  • Ephemeral back-and-forth conversation
  • Information already stored (recall first to check)
  • Raw data dumps (summarize first)

​
Best practices

  1. Be specific — “Ana prefers VSCode with vim bindings” beats “user likes editors”
  2. Add metadata — Tags enable filtered recall later
  3. Set importance — 0.9+ for critical info, 0.5 for nice-to-have
  4. Use namespaces — Isolate memories per project
  5. Don’t duplicate — Recall before storing similar content
  6. Respect privacy — Never store secrets