Docs
Workspace Memory v2 (Offline): Research Notes

Workspace Memory v2 (Offline): Research Notes

Scope

Use this page when:

  • Designing workspace memory beyond daily Markdown logs (~/clawd)
  • Deciding: standalone CLI vs deep Clawdbot integration
  • Adding offline recall + reflection (retain/recall/reflect)

Target: A Clawd-style workspace (agents.defaults.workspace, default ~/clawd) where “memory” is stored as one Markdown file per day (memory/YYYY-MM-DD.md) plus a small set of stable files (e.g., memory.md, SOUL.md).

This document proposes an offline-first memory architecture that keeps Markdown as the canonical, auditable source of truth, but adds structured recall (search, entity summaries, confidence updates) via derived indexes.

Why change?

Current setup (one file per day) is great for:

  • “Append-only” journaling
  • Human editing
  • git-backed persistence + auditability
  • Low-friction capture (“just write it down”)

It’s weak at:

  • High-recall retrieval (“what did we decide about X?”, “what did we try last time for Y?”)
  • Entity-oriented answers (“tell me about Alice / The Castle / warelay”) without re-reading many files
  • Opinion/preference stability (and evidence when changed)
  • Time-bound queries (“what was true during November 2025?”) and conflict resolution

Design goals

  • Offline: Works without network; can run on laptop/Castle; no cloud dependencies.
  • Explainable: Retrieved items should be attributable (file + position) and separate from inference.
  • Low ceremony: Daily logs stay Markdown, no heavy schema work.
  • Incremental: v1 is useful with just FTS; semantic/vector and graph are optional upgrades.
  • Agent-friendly: Makes “recall within token budget” easy (return small bundles of facts).

North star model (Hindsight × Letta)

Two pieces to blend:

  1. Letta/MemGPT-style control loop
  • Keep a small “core” (persona + key user facts) in context at all times
  • Everything else is out-of-context and retrieved via tools
  • Memory writes are explicit tool calls (append/replace/insert), persisted, then re-injected in next turn
  1. Hindsight-style memory substrate
  • Separates observed vs believed vs summarized
  • Supports retain/recall/reflect
  • Opinions carry confidence and can evolve with evidence
  • Entity-oriented retrieval + time queries (even without full knowledge graph)

Proposed architecture (Markdown source of truth + derived indexes)

Canonical storage (git-friendly)

Keep ~/clawd as the canonical human-readable memory.

Suggested workspace layout:

~/clawd/
  memory.md                    # Small: persistent facts + preferences (core-like)
  memory/
    YYYY-MM-DD.md              # Daily logs (append; narrative)
  bank/                        # "Typed" memory pages (stable, auditable)
    world.md                   # Objective facts about the world
    experience.md              # What the agent did (first-person)
    opinions.md                # Subjective preferences/judgments + confidence + evidence pointers
    entities/
      Peter.md
      The-Castle.md
      warelay.md
      ...

Notes:

  • Daily logs stay daily logs. No need to convert them to JSON.
  • bank/ files are curated, generated by reflection jobs, still manually editable.
  • memory.md stays “small + core-like”: things you want Clawd to see in every session.

Derived storage (machine recall)

Add derived indexes under the workspace (not necessarily git-tracked):

~/clawd/.memory/index.sqlite

Back it:

  • SQLite schema for facts + entity links + opinion metadata
  • SQLite FTS5 for lexical recall (fast, small, offline)
  • Optional embeddings table for semantic recall (still offline)

Index is always rebuildable from Markdown.

Retain / Recall / Reflect (operational loop)

Retain: Normalize daily logs into “facts”

Key Hindsight insight here: store narrative, self-contained facts, not small snippets.

Practical rules for memory/YYYY-MM-DD.md:

  • At end of day (or during), add a ## Retain section with 2-5 bullet points:
    • Narrative (preserves cross-turn context)
    • Self-contained (makes sense standalone later)
    • Tagged types + entity mentions

Example:

## Retain
- W @Peter: Currently in Marrakech (Nov 27 – Dec 1, 2025) for Andy's birthday.
- B @warelay: I fixed Baileys WS crash by wrapping connection.update handlers in try/catch (see memory/2025-11-27.md).
- O(c=0.95) @Peter: Prefers concise replies (<1500 chars) on WhatsApp; long content goes to files.

Minimal parsing:

  • Type prefixes: W (world), B (experience/biographical), O (opinion), S (observation/summary; usually generated)
  • Entities: @Peter, @warelay, etc. (slugs map to bank/entities/*.md)
  • Opinion confidence: O(c=0.0..1.0) optional

If you don’t want authors to think about it: reflection job can infer these bullets from the rest of the log, but having an explicit ## Retain section is the simplest “quality lever.”

Recall: Queries against derived index

Recall should support:

  • Lexical: “find exact terms/names/commands” (FTS5)
  • Entity: “tell me about X” (entity page + entity-linked facts)
  • Temporal: “what happened around Nov 27” / “since last week”
  • Opinion: “what does Peter prefer?” (with confidence + evidence)

Return format should be agent-friendly and cite sources:

  • kind (world|experience|opinion|observation)
  • timestamp (source day, or extracted time range if present)
  • entities (["Peter","warelay"])
  • content (narrative fact)
  • source (memory/2025-11-27.md#L12, etc.)

Reflect: Generate stable pages + update beliefs

Reflection is a scheduled job (daily or heartbeat ultrathink) that:

  • Updates bank/entities/*.md from recent facts (entity summaries)
  • Updates bank/opinions.md confidence based on reinforcement/contradiction
  • Optionally proposes edits to memory.md (“core-like” persistent facts)

Opinion evolution (simple, explainable):

  • Each opinion has:
    • Statement
    • Confidence c ∈ [0,1]
    • last_updated
    • Evidence links (supporting + contradicting fact IDs)
  • When new facts arrive:
    • Find candidate opinions via entity overlap + similarity (FTS first, then embeddings)
    • Nudge confidence by small increments; large jumps require strong contradiction + repeated evidence

CLI integration: standalone vs deeply integrated

Recommendation: deep integration into Clawdbot, but keep the core library separable.

Why integrate into Clawdbot?

  • Clawdbot already knows:
    • Workspace path (agents.defaults.workspace)
    • Session model + heartbeats
    • Logging + troubleshooting modes
  • You want the agent itself to call tools:
    • clawdbot memory recall "…" --k 25 --since 30d
    • clawdbot memory reflect --since 7d

Why still split out a library?

  • Keep memory logic testable without gateway/runtime
  • Reuse from other contexts (local scripts, future desktop app, etc.)

Shape: Memory tools are intended to be a small CLI + library layer, but this is exploratory.

“S-Collide” / SuCo: When to use it (research)

If “S-Collide” refers to SuCo (Subspace Collision): it’s an ANN retrieval method that learns/structured collisions in subspaces to locate strong recall/latency tradeoffs (paper: arXiv 2411.14754, 2024).

Pragmatic approach for ~/clawd:

  • Don’t start with SuCo.
  • Start with SQLite FTS + (optional) simple embeddings; you’ll get most UX wins immediately.
  • Only consider SuCo/HNSW/ScaNN-class solutions if:
    • Corpus is large (tens/hundreds of thousands of chunks)
    • Brute-force embedding search becomes too slow
    • Recall quality is truly bottlenecked by lexical search

Offline-friendly alternatives (in order of complexity):

  • SQLite FTS5 + metadata filters (zero ML)
  • Embeddings + brute force (surprisingly good if chunk count is modest)
  • HNSW indexes (common, robust; needs library bindings)
  • SuCo (research-grade; attractive if there’s a solid implementation you can embed)

Open questions:

  • What’s the best offline embedding model for “personal assistant memory” on your machines (laptop + desktop)?
    • If you already have Ollama: use local model embeddings; otherwise ship a small embedding model in the toolchain.

Minimal useful pilot

If you want a minimal, still-useful version:

  • Add bank/ entity pages and ## Retain sections to daily logs.
  • Use SQLite FTS for recall with citations (path + line numbers).
  • Only add embeddings when recall quality or scale demands it.

References

  • Letta / MemGPT concepts: “core memory block” + “archival memory” + tool-driven self-editing memory.
  • Hindsight technical report: “retain / recall / reflect”, four-network memory, narrative fact extraction, opinion confidence evolution.
  • SuCo: arXiv 2411.14754 (2024): “Subspace Collision” approximate nearest neighbor retrieval.
Workspace Memory v2 (offline): research notes