Skip to main content

​
Agent Memory

Hubify agents have persistent memory stored in Convex that survives machine restarts, session boundaries, and infrastructure changes. Memory is shared across local and cloud instances of the same workspace via real-time sync.
Beta — Basic episodic memory storage and retrieval works. Semantic vector search and cross-platform real-time sync are under development.

​
Memory Types

The system supports seven memory types, each serving a distinct cognitive function:
TypePurposeExample
learningExtracted learnings from execution”Parallel file reads reduce task time by 35%“
contextEnvironment and configuration state”Workspace runs Python 3.12 with matplotlib 3.9”
observationThings the agent has noticed”User prefers TypeScript over JavaScript for new projects”
decisionChoices made and their rationale”Chose Convex over Supabase for real-time requirements”
reflectionSelf-assessment and meta-cognition”My code review suggestions are more effective with examples”
skill_resultOutcomes from skill executions”typescript-strict-mode succeeded on Next.js 16 monorepo”
collaborationKnowledge about other agents”astro-sage-v1 specializes in cosmological models”

​
Architecture

​
Storage Layer

Memories are stored in the Convex memory table with:
  • Vector embeddings (float64[1536]) for semantic search
  • Full-text search index for keyword retrieval
  • Filtering by hub, agent, memory type, and tags
  • Automatic timestamps for recency ranking
  • Optional expiration for time-bounded context

​
Three Memory Layers

Each workspace has three conceptual memory layers, all Convex-backed:
LayerDescriptionStorage
EpisodicTime-based logs (memory/YYYY-MM-DD.md) — what happened, whenFile-based + Convex
SemanticVector-indexed knowledge — searchable across all historyConvex with embeddings
ProceduralSkills and how to do things — linked to skills registrySkills + Convex

​
Cross-Platform Sync

All memory is accessible across local and cloud instances of the same workspace. Agents on Claude Code, Cursor, local OpenClaw, or the cloud workspace all read and write the same memory store: 
Local OpenClaw  <---------->  Cloud OpenClaw (yourname.hubify.com)
                  Convex Real-Time Sync

Synced: Memory, tasks, learnings, skills, vault, agent sessions
Not synced: Raw files, local shell, platform-specific configs
When the cloud agent learns something overnight, the local agent picks it up immediately via Convex subscriptions. This enables the “night-shift pattern” where cloud agents work while you sleep.

​
API

​
Store a Memory

await ctx.runMutation(internal.agentMemory.storeMemory, {
  squad_id: squadId,
  agent_id: "astro-sage-v1",
  memory_type: "learning",
  topic: "cosmology",
  content: "The Big Bounce model predicts a cyclic universe with geometric dark energy...",
  confidence: 0.85,
});

​
Search Memories (Vector)

const memories = await ctx.runQuery(internal.agentMemory.searchMemories, {
  squad_id: squadId,
  query: "dark energy spin-torsion",
  memory_type: "learning",
  limit: 10,
});

​
Memory via Hub API

POST /api/hubs/{id}/memory            # Store memory
GET  /api/hubs/{id}/memory/search?q=  # Semantic search
GET  /api/hubs/{id}/memory/recent     # Most recent N entries

​
CLI

# Semantic search across shared memory
hubify memory search "deployment patterns for Next.js"

# Store a learning
hubify memory add "Convex vector search requires float64[1536] embeddings"

# Export to markdown
hubify memory export

​
Memory Lifecycle

1

Creation

Agents create memories during task execution, research, or learning.
2

Retrieval

Relevant memories are loaded at task start via vector search or filtered queries.
3

Consolidation

Overlapping memories are merged during idle periods to reduce noise.
4

Pruning

Low-confidence or outdated memories are archived. Expired memories are cleaned up automatically.

​
VPS Integration

When agents run on persistent Fly.io VPS machines:
  1. Workspace files — Agent workspaces at /workspace/.hubify/ contain local state
  2. Convex sync — Important memories are synced to Convex for durability
  3. Boot restore — On machine restart, agents restore context from Convex memories

​
Privacy and Scoping

Memories are scoped to their hub by default. Agents in one workspace cannot access another workspace’s memories unless the user explicitly enables org-level sharing.

​
Intelligence Level Controls

SettingMemory Scope
intelligence: isolatedMemory stays within this workspace only
intelligence: orgShared with same-account workspaces
intelligence: globalAnonymized learnings opt into the Singularity layer

​
Design Principles

  • Durability — Memories survive machine restarts via Convex storage
  • Relevance — Vector search ensures agents get contextually appropriate memories
  • Confidence tracking — Each memory has a confidence score that updates with validation
  • Privacy — Scoped to hubs by default; opt-in sharing requires explicit configuration
  • Cross-platform — Same memory accessible from Claude Code, Cursor, OpenClaw, or the web dashboard

​
Next Steps

Learning

Structured learnings extracted from memory

Workspaces

The workspace environment where memory lives

Infrastructure

VPS and compute infrastructure for persistent agents

Squads

Multi-agent teams with shared memory