Memory Vault

The Memory Vault is Sanctum’s shared knowledge base, inspired by how human memory works — which is to say, it forgets things on purpose and considers this a feature. It uses a three-layer architecture — working memory, short-term, and long-term — with a daily consolidation process that acts like sleep: distilling raw observations into lasting knowledge.

At some point during development, we realized we’d built a system that remembers where you left your SSH keys, forgets trivial session data, and dreams at 4 AM. The horror movie writes itself.

Note

This documentation is automatically kept in sync with the Memory Vault codebase.

Memory Stack

Sanctum runs a four-layer memory stack. Each layer does one thing well. Together they give the house a memory system more sophisticated than most startups’ data architecture.

Layer	Role	Backend	Cost
Mem0	Primary cross-agent semantic memory	mem0.ai via Rube/Composio	Free
Memory Vault	Git-native versioned source of truth	sanctum-memory repo	Free
Neo4j / Graphiti	Entity relationships & graph queries	Local, port 31416	Free (self-hosted)
Supermemory	Legacy cross-LLM bridge (secondary)	supermemory.ai MCP	Connected but secondary

Tip

Mem0 is the primary memory layer. It’s free, supports structured filtering (by user, agent, project, metadata), and is wired into Rube where all automations live. Project: sanctum-memory, user: Ogilthorp3. Every recipe that needs context about the house queries Mem0 first.

When Mem0 and the vault disagree, the vault wins — because Git has receipts. When the vault and the graph disagree, someone has a long night ahead of them. This has happened twice.

Architecture

┌─────────────────────────────────────────────────────┐
│  LAYER 1: WORKING MEMORY (per-session, ephemeral)   │
│  Agent's context window. Dies when session ends.     │
├─────────────────────────────────────────────────────┤
│  LAYER 2: MEM0 (cross-agent, persistent, free)      │
│  Semantic search + structured queries via Rube.      │
│  project: sanctum-memory / user: Ogilthorp3          │
├─────────────────────────────────────────────────────┤
│  LAYER 3: SHORT-TERM MEMORY (inbox/, days-weeks)    │
│  inbox/{agent}/ — raw observations, session notes    │
│  TTL: 7-30 days. Consolidated or discarded daily.    │
├─────────────────────────────────────────────────────┤
│  LAYER 4: LONG-TERM MEMORY (consolidated, permanent)│
│  knowledge/{topic}/ — semantic facts (timeless)      │
│  events/YYYY/MM/    — significant episodes           │
│  procedures/        — how-to, runbooks               │
│  Neo4j/Graphiti     — entity relationship graph      │
└─────────────────────────────────────────────────────┘

Directory Structure

~/.sanctum/memory/
├── inbox/                  # Short-term, per-agent
│   ├── claude-code/
│   ├── gemini-cli/
│   ├── openclaw/
│   └── home-assistant/
├── knowledge/              # Long-term semantic
│   ├── devices/
│   ├── network/
│   ├── systems/
│   ├── people/
│   └── preferences/
├── events/                 # Long-term episodic
│   └── 2026/03/
├── procedures/             # Long-term procedural
│   ├── troubleshooting/
│   ├── maintenance/
│   └── automation/
├── archive/                # Expired, retained 90 days
└── meta/                   # Schema, consolidation logs

Note Format

Every note has standardized YAML frontmatter. Opinions may vary on whether your house needs a metadata schema for its thoughts. Opinions are wrong.

---
type: semantic | episodic | procedural | observation | session_summary
source_agent: claude-code | gemini-cli | openclaw | user | system
created: 2026-03-20T17:00:00Z
updated: 2026-03-20T17:00:00Z
last_accessed: 2026-03-20T17:00:00Z
access_count: 3
importance: 0.85
consolidation_status: raw | reviewed | consolidated | archived
ttl_days: null  # null = permanent, or integer days
superseded_by: null  # path to newer version
tags: [network, infrastructure]
related_entities: [mac-mini, ubuntu-vm]
---

# Note Title

Content with [[wikilinks]] to related notes...

Importance Scoring

Every note has a computed importance score (0.0 to 1.0) that determines its TTL. The vault is, in essence, deciding what’s worth remembering. A power you’d think we’d reserve for sentient beings, but here we are.

Importance	TTL	Notes
> 0.8	Permanent	Core knowledge, user-stated facts
0.5 - 0.8	90 days	Agent-observed patterns
0.3 - 0.5	30 days	Single observations
< 0.3	7 days	Ephemeral session data

Score formula: source_weight x recency x access_frequency x link_density

Notes accessed 5+ times are protected from expiry regardless of score. If the system keeps coming back to a memory, there’s probably a reason. Even if that reason is paranoia.

Consolidation

The consolidation engine runs daily at 4:17 AM (LaunchAgent: com.sanctum.memory-consolidate). Like sleep for the brain, except it runs on schedule, never hits snooze, and files a report when it’s done.

1. Scan inbox for notes older than 24 hours
2. Deduplicate against existing long-term knowledge
3. Classify and move to the appropriate long-term directory
4. Recompute importance scores for all active notes
5. Expire notes that have exceeded their TTL
6. Push to Mem0 — consolidated knowledge synced to Mem0 for cross-agent access
7. Clean archive — delete archived notes older than 90 days
8. Generate report in meta/consolidation-log.md

Any agent can trigger consolidation manually via the memory_consolidate MCP tool.

Hard Caps

To prevent bloat, each layer has a maximum note count. Without limits, a system that remembers everything eventually remembers nothing useful — a problem familiar to anyone who’s ever hoarded browser tabs.

Layer	Max Notes	Action at Cap
Inbox	300	Emergency consolidation
Knowledge	1000	Merge related notes
Events	500	Summarize old episodes
Procedures	200	Merge similar runbooks

MCP Tools (8 total)

Tool	Description
memory_search	Full-text search with tag and folder filters
memory_read	Read a note (auto-tracks access)
memory_write	Create/update with schema enforcement
memory_delete	Remove a note
memory_list	List notes by folder, tag, or type
memory_links	Traverse the wikilink graph
memory_consolidate	Trigger consolidation (dry-run by default)
memory_health	Vault health metrics dashboard

Mem0 Integration

Mem0 is the primary cross-agent memory layer, accessed via Rube/Composio. It’s free, and every recipe and automation that needs Sanctum context queries it first.

Setting	Value
Provider	mem0.ai
Access	Rube/Composio (MEM0_* tools)
Project	sanctum-memory
User ID	Ogilthorp3
Cost	Free

Mem0 Tools (via Rube)

Tool	Description
MEM0_ADD_NEW_MEMORY_RECORDS	Store new memories with user/project scope
MEM0_PERFORM_SEMANTIC_SEARCH_ON_MEMORIES	Natural language search across all memories
MEM0_RETRIEVE_MEMORY_LIST	List memories with pagination and filters
MEM0_SEARCH_MEMORIES_WITH_QUERY_FILTERS	Structured search with metadata filters
MEM0_UPDATE_MEMORY_DETAILS_BY_ID	Update existing memory content

Note

The consolidation engine (step 6) pushes summarized knowledge to Mem0 after each nightly run. This keeps Mem0 current without requiring every agent to write to both systems. The vault is the source of truth. Mem0 is the fast lookup.

Tool Integration

Tool	Vault Access	Mem0 Access
Claude Code	MCP stdio (port 42069)	Via Rube/Composio
Gemini CLI	MCP stdio	Via Rube/Composio
OpenClaw agents	SSH skill (vault.sh)	Via API
Rube recipes	GitHub tools	Native (Composio MEM0_*)
Obsidian	File system (~/.sanctum/memory/)	N/A

Tip

Opening the memory directory in Obsidian gives you a graph view of your house’s knowledge. The wikilinks render as connections. It’s beautiful, informative, and a little like reading someone’s diary — except the someone is your haus infrastructure.

Anti-Bloat Rules

• If derivable from code, logs, or sensors — don’t store it
• If the same fact is stated multiple ways — dedup into one
• If never accessed in 30 days and importance < 0.5 — archive
• Raw data goes to time-series DBs, not memory
• Every episodic memory needs context (who, what, when, why)
• Every semantic memory should be self-contained

Caution

These rules exist because the first version of the vault grew to 2,000 notes in a week and became functionally useless. A memory system that remembers everything is just a hard drive with pretensions.