730 lines
28 KiB
HTML
730 lines
28 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Clawdbot Memory System — Guide v2.0</title>
|
|
<style>
|
|
/* ── Reset & Base ── */
|
|
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
|
|
|
html {
|
|
font-size: 14px;
|
|
-webkit-print-color-adjust: exact;
|
|
print-color-adjust: exact;
|
|
}
|
|
|
|
body {
|
|
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
|
|
color: #1a1a2e;
|
|
background: #ffffff;
|
|
line-height: 1.5;
|
|
max-width: 800px;
|
|
margin: 0 auto;
|
|
padding: 0 24px;
|
|
}
|
|
|
|
/* ── Typography ── */
|
|
h1 { font-size: 1.8rem; font-weight: 800; color: #0f0f23; margin-bottom: 0.3em; letter-spacing: -0.02em; }
|
|
h2 { font-size: 1.65rem; font-weight: 700; color: #1a1a3e; margin-bottom: 0.4em; margin-top: 1.2em; letter-spacing: -0.01em; }
|
|
h3 { font-size: 1.2rem; font-weight: 700; color: #2a2a4e; margin-bottom: 0.4em; margin-top: 1.4em; }
|
|
h4 { font-size: 1.05rem; font-weight: 600; color: #3a3a5e; margin-bottom: 0.3em; margin-top: 1em; }
|
|
p { margin-bottom: 0.7em; }
|
|
|
|
/* ── Images ── */
|
|
.diagram {
|
|
display: block;
|
|
max-width: 100%;
|
|
margin: 1.5em auto;
|
|
border-radius: 12px;
|
|
box-shadow: 0 4px 24px rgba(0,0,0,0.12);
|
|
}
|
|
|
|
/* ── Blockquote ── */
|
|
blockquote {
|
|
border-left: 4px solid #6c5ce7;
|
|
background: #f8f7ff;
|
|
padding: 1em 1.2em;
|
|
margin: 1.5em 0;
|
|
border-radius: 0 8px 8px 0;
|
|
font-style: italic;
|
|
color: #444;
|
|
}
|
|
blockquote cite {
|
|
display: block;
|
|
margin-top: 0.5em;
|
|
font-style: normal;
|
|
font-weight: 600;
|
|
color: #6c5ce7;
|
|
}
|
|
|
|
/* ── Code ── */
|
|
code {
|
|
font-family: "SF Mono", "Fira Code", "JetBrains Mono", Menlo, Consolas, monospace;
|
|
background: #f0f0f8;
|
|
padding: 0.15em 0.4em;
|
|
border-radius: 4px;
|
|
font-size: 0.88em;
|
|
color: #d63384;
|
|
}
|
|
pre {
|
|
background: #0f0f23;
|
|
color: #e0e0ff;
|
|
padding: 1em 1.2em;
|
|
border-radius: 10px;
|
|
overflow-x: auto;
|
|
margin: 1.2em 0;
|
|
font-size: 0.85rem;
|
|
line-height: 1.5;
|
|
box-shadow: 0 2px 12px rgba(0,0,0,0.15);
|
|
}
|
|
pre code {
|
|
background: none;
|
|
color: inherit;
|
|
padding: 0;
|
|
font-size: inherit;
|
|
}
|
|
|
|
/* ── Tables ── */
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 1.2em 0;
|
|
font-size: 0.92rem;
|
|
}
|
|
th {
|
|
background: #1a1a3e;
|
|
color: #fff;
|
|
padding: 0.7em 1em;
|
|
text-align: left;
|
|
font-weight: 600;
|
|
font-size: 0.85rem;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.04em;
|
|
}
|
|
th:first-child { border-radius: 8px 0 0 0; }
|
|
th:last-child { border-radius: 0 8px 0 0; }
|
|
td {
|
|
padding: 0.6em 1em;
|
|
border-bottom: 1px solid #eee;
|
|
color: #333;
|
|
}
|
|
tr:nth-child(even) td { background: #fafaff; }
|
|
tr:last-child td:first-child { border-radius: 0 0 0 8px; }
|
|
tr:last-child td:last-child { border-radius: 0 0 8px 0; }
|
|
|
|
/* ── Lists ── */
|
|
ul, ol { margin-left: 1.5em; margin-bottom: 1em; }
|
|
li { margin-bottom: 0.35em; }
|
|
li::marker { color: #6c5ce7; }
|
|
|
|
/* ── Accent boxes ── */
|
|
.cause-box {
|
|
background: #fff;
|
|
border: 1px solid #e8e8f0;
|
|
border-radius: 12px;
|
|
padding: 1.2em 1.4em;
|
|
margin: 1em 0;
|
|
box-shadow: 0 2px 8px rgba(0,0,0,0.04);
|
|
}
|
|
.cause-box h4 { margin-top: 0; }
|
|
.problem-label {
|
|
display: inline-block;
|
|
background: #fff0f0;
|
|
color: #cc3333;
|
|
padding: 0.15em 0.6em;
|
|
border-radius: 4px;
|
|
font-size: 0.78rem;
|
|
font-weight: 700;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.04em;
|
|
margin-bottom: 0.3em;
|
|
}
|
|
.fix-label {
|
|
display: inline-block;
|
|
background: #f0fff0;
|
|
color: #228822;
|
|
padding: 0.15em 0.6em;
|
|
border-radius: 4px;
|
|
font-size: 0.78rem;
|
|
font-weight: 700;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.04em;
|
|
margin-bottom: 0.3em;
|
|
}
|
|
|
|
/* ── Install Steps ── */
|
|
.install-step {
|
|
display: flex;
|
|
align-items: flex-start;
|
|
gap: 1em;
|
|
margin: 0.8em 0;
|
|
padding: 0.8em;
|
|
background: #fafaff;
|
|
border-radius: 8px;
|
|
}
|
|
.install-step .step-num {
|
|
background: #6c5ce7;
|
|
color: #fff;
|
|
width: 28px;
|
|
height: 28px;
|
|
border-radius: 50%;
|
|
display: flex;
|
|
align-items: center;
|
|
justify-content: center;
|
|
font-weight: 700;
|
|
font-size: 0.85rem;
|
|
flex-shrink: 0;
|
|
margin-top: 2px;
|
|
}
|
|
.install-step .step-text strong { color: #1a1a3e; }
|
|
.install-step .recommended {
|
|
color: #6c5ce7;
|
|
font-weight: 600;
|
|
font-size: 0.85em;
|
|
}
|
|
|
|
/* ── Feature grid ── */
|
|
.feature-section {
|
|
border: 1px solid #e8e8f0;
|
|
border-radius: 12px;
|
|
padding: 1.2em 1.4em;
|
|
margin: 1em 0;
|
|
background: #fafaff;
|
|
}
|
|
.feature-section h3 {
|
|
margin-top: 0;
|
|
color: #6c5ce7;
|
|
}
|
|
.feature-section.optional { border-left: 4px solid #ffa726; }
|
|
.feature-section.optional h3 { color: #e67e22; }
|
|
.feature-section.core { border-left: 4px solid #6c5ce7; }
|
|
.badge {
|
|
display: inline-block;
|
|
padding: 0.1em 0.5em;
|
|
border-radius: 4px;
|
|
font-size: 0.72rem;
|
|
font-weight: 700;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.03em;
|
|
margin-left: 0.5em;
|
|
vertical-align: middle;
|
|
}
|
|
.badge.core-badge { background: #ece8ff; color: #6c5ce7; }
|
|
.badge.optional-badge { background: #fff3e0; color: #e67e22; }
|
|
|
|
/* ── Stats ── */
|
|
.stats-grid {
|
|
display: grid;
|
|
grid-template-columns: repeat(4, 1fr);
|
|
gap: 1em;
|
|
margin: 1.5em 0;
|
|
}
|
|
.stat-card {
|
|
text-align: center;
|
|
background: #fafaff;
|
|
border: 1px solid #e8e8f0;
|
|
border-radius: 10px;
|
|
padding: 1em 0.5em;
|
|
}
|
|
.stat-card .stat-value {
|
|
font-size: 1.6rem;
|
|
font-weight: 800;
|
|
color: #6c5ce7;
|
|
display: block;
|
|
}
|
|
.stat-card .stat-label {
|
|
font-size: 0.78rem;
|
|
color: #888;
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.03em;
|
|
margin-top: 0.3em;
|
|
}
|
|
|
|
/* ── Limitation boxes ── */
|
|
.limitation {
|
|
background: #fffbf0;
|
|
border: 1px solid #ffe0a0;
|
|
border-radius: 8px;
|
|
padding: 0.8em 1em;
|
|
margin: 0.6em 0;
|
|
font-size: 0.92rem;
|
|
}
|
|
.limitation strong { color: #cc8800; }
|
|
|
|
/* ── Cover Page ── */
|
|
.cover {
|
|
display: flex;
|
|
flex-direction: column;
|
|
justify-content: center;
|
|
align-items: center;
|
|
min-height: 90vh;
|
|
text-align: center;
|
|
padding: 2em 0;
|
|
}
|
|
.cover .emoji-hero { font-size: 5rem; margin-bottom: 0.2em; line-height: 1; }
|
|
.cover h1 { font-size: 2.8rem; margin-bottom: 0.15em; }
|
|
.cover .subtitle {
|
|
font-size: 1.3rem;
|
|
color: #6c5ce7;
|
|
font-weight: 500;
|
|
margin-bottom: 2em;
|
|
}
|
|
.cover .byline {
|
|
font-size: 1rem;
|
|
color: #888;
|
|
margin-bottom: 0.3em;
|
|
}
|
|
.cover .version {
|
|
font-size: 0.9rem;
|
|
color: #aaa;
|
|
margin-top: 0.8em;
|
|
padding-top: 0.8em;
|
|
border-top: 1px solid #eee;
|
|
}
|
|
.cover .logo-accent {
|
|
width: 120px;
|
|
height: 4px;
|
|
background: linear-gradient(90deg, #6c5ce7, #00ccff);
|
|
border-radius: 2px;
|
|
margin: 1.5em auto;
|
|
}
|
|
|
|
/* ── Footer ── */
|
|
.page-footer {
|
|
text-align: center;
|
|
font-size: 0.75rem;
|
|
color: #999;
|
|
padding: 1em 0 0.5em;
|
|
border-top: 1px solid #eee;
|
|
margin-top: 1.5em;
|
|
}
|
|
|
|
/* ── Page Breaks ── */
|
|
.page-break { page-break-before: always; }
|
|
h2 { page-break-after: avoid; }
|
|
h3 { page-break-after: avoid; }
|
|
.cause-box { page-break-inside: avoid; }
|
|
.feature-card { page-break-inside: avoid; }
|
|
.stat-grid { page-break-inside: avoid; }
|
|
.install-step { page-break-inside: avoid; }
|
|
svg { page-break-inside: avoid; }
|
|
|
|
/* ── Seamless list ── */
|
|
.seamless-point {
|
|
display: flex;
|
|
gap: 0.8em;
|
|
margin: 0.8em 0;
|
|
align-items: flex-start;
|
|
}
|
|
.seamless-point .icon {
|
|
font-size: 1.3rem;
|
|
flex-shrink: 0;
|
|
margin-top: 0.05em;
|
|
}
|
|
.seamless-point .text { flex: 1; }
|
|
|
|
/* ── Print Styles ── */
|
|
@media print {
|
|
body { max-width: 100%; padding: 0; font-size: 11pt; }
|
|
.page-break { page-break-before: always; }
|
|
h2 { page-break-after: avoid; }
|
|
h3 { page-break-after: avoid; }
|
|
.cause-box { page-break-inside: avoid; }
|
|
.feature-card { page-break-inside: avoid; }
|
|
.stat-grid { page-break-inside: avoid; }
|
|
h2 { page-break-after: avoid; }
|
|
h3 { page-break-after: avoid; }
|
|
.cause-box { page-break-inside: avoid; }
|
|
.feature-card { page-break-inside: avoid; }
|
|
.stat-grid { page-break-inside: avoid; }
|
|
.install-step { page-break-inside: avoid; }
|
|
svg { page-break-inside: avoid; }
|
|
.cover { min-height: auto; }
|
|
pre { font-size: 9pt; }
|
|
.diagram { box-shadow: none; border: 1px solid #ddd; }
|
|
.page-footer { position: relative; }
|
|
a { color: #6c5ce7; text-decoration: none; }
|
|
.stats-grid { gap: 0.6em; }
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- COVER PAGE -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<div class="cover">
|
|
<div class="emoji-hero">🧠</div>
|
|
<h1>Clawdbot Memory System</h1>
|
|
<div class="subtitle">Never lose context to compaction again.</div>
|
|
<div class="logo-accent"></div>
|
|
<div class="byline">Built by <strong>Jake Shore</strong> & <strong>Buba</strong></div>
|
|
<div class="version">Version 2.0 | February 2026</div>
|
|
</div>
|
|
<hr style="border:none;border-top:2px solid #e0e0e0;margin:2em 0;">
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 1: THE PROBLEM -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>Why Your Agent Forgets Everything</h2>
|
|
|
|
<p>
|
|
You've spent hours building context with your AI agent. You've explained your project architecture, your preferences, your entire business setup. Then the next morning, you say <em>"Hey, remember that API integration we worked on?"</em> and get back: <em>"I don't have any context about a previous API integration. Could you tell me more?"</em>
|
|
</p>
|
|
|
|
<p>
|
|
This isn't a bug — it's how AI agents are designed. When your conversation gets too long, the system runs <strong>compaction</strong>: it summarizes the conversation to free up context space. The summary keeps the gist, but the details — the exact config values, the specific decisions you made, the nuances of your preferences — those get compressed into oblivion. Your agent essentially gets amnesia.
|
|
</p>
|
|
|
|
<p>
|
|
The problem is structural. Every AI assistant today — Claude, ChatGPT, Gemini, all of them — faces this same constraint. Context windows are finite. Compaction is inevitable. And without a system to persist knowledge outside the chat window, everything you build is written in sand.
|
|
</p>
|
|
|
|
<img src="amnesia-problem-solution.svg" alt="The Problem vs The Solution" class="diagram"/>
|
|
|
|
<blockquote>
|
|
"My buddies hate when their agent just gets amnesia."
|
|
<cite>— Jake</cite>
|
|
</blockquote>
|
|
|
|
<p>
|
|
The Clawdbot Memory System solves this completely. It gives your agent a persistent memory layer — a real filesystem-backed brain that survives compaction, survives restarts, survives everything. Your agent writes knowledge to disk continuously and reads it back automatically. No more amnesia. No more re-explaining yourself.
|
|
</p>
|
|
|
|
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 2: THREE CAUSES & FIXES -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>The Three Causes (and How We Fix Them)</h2>
|
|
|
|
<p>Agent amnesia isn't one problem — it's three separate failure modes stacked on top of each other. We engineered a fix for each one.</p>
|
|
|
|
<img src="three-causes-fix.svg" alt="Three Causes and Their Fixes" class="diagram"/>
|
|
|
|
<div class="cause-box">
|
|
<h4>Cause 1: Agent Never Writes Anything Down</h4>
|
|
<span class="problem-label">Problem</span>
|
|
<p>
|
|
Everything your agent knows lives exclusively in the chat context window. When compaction fires, the system generates a brief summary and discards the full conversation. Specific details — the exact configuration values you discussed, the precise reasoning behind a decision, your stated preferences — all get lost in summarization.
|
|
</p>
|
|
<span class="fix-label">Fix</span>
|
|
<p>
|
|
<code>AGENTS.md</code> instructs the agent to write to <code>memory/YYYY-MM-DD.md</code> <strong>throughout the session</strong> — not at the end, but continuously. Every decision, preference, project update, and notable piece of context gets written to disk in real-time. Even if compaction fires immediately after, the knowledge is already safely persisted.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="cause-box">
|
|
<h4>Cause 2: Compaction Fires Before the Agent Can Save</h4>
|
|
<span class="problem-label">Problem</span>
|
|
<p>
|
|
Even with continuous writing, there's a race condition. The session hits its token limit, compaction fires immediately, and any context accumulated since the last write is gone. The agent doesn't get a chance to save before the rug is pulled out.
|
|
</p>
|
|
<span class="fix-label">Fix</span>
|
|
<p>
|
|
<strong>Pre-compaction flush.</strong> When the session is approximately 4,000 tokens from the compaction threshold, Clawdbot triggers a silent turn. The agent receives a system-level instruction to flush all unsaved context to disk immediately. It saves everything, responds with <code>NO_REPLY</code> (the user never sees this turn), and <em>then</em> compaction proceeds safely. Zero data loss.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="cause-box">
|
|
<h4>Cause 3: Agent Doesn't Check Memory on New Sessions</h4>
|
|
<span class="problem-label">Problem</span>
|
|
<p>
|
|
Even if memories exist on disk, a fresh session starts with a clean slate. The agent has no idea those memory files are there unless something tells it to look. So it starts from zero every time — the knowledge exists but is never retrieved.
|
|
</p>
|
|
<span class="fix-label">Fix</span>
|
|
<p>
|
|
<strong>Mandatory Memory Recall</strong> rule baked into <code>AGENTS.md</code>: before answering <em>any</em> question about prior work, the agent MUST run <code>memory_search</code> first. Additionally, on every session start, the agent automatically reads today's and yesterday's logs. The result: the agent always knows what you've been working on.
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 3: HOW IT WORKS -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>How It Works</h2>
|
|
|
|
<p>The system uses a <strong>two-layer architecture</strong> designed for both human readability and machine-speed retrieval.</p>
|
|
|
|
<img src="memory-system-architecture.svg" alt="Two-Layer Memory Architecture" class="diagram"/>
|
|
|
|
<h3>Layer 1: Markdown Files (Source of Truth)</h3>
|
|
<p>
|
|
All memories are stored as plain Markdown files in the <code>memory/</code> directory. Daily logs follow the <code>YYYY-MM-DD.md</code> convention. Project files, research intel, and contacts all live as readable <code>.md</code> files. This layer is human-readable, git-backed, and editable. You can open any memory file in your text editor and read exactly what your agent knows. This is the source of truth — everything else is derived from it.
|
|
</p>
|
|
|
|
<h3>Layer 2: SQLite + Vector Embeddings (Search Engine)</h3>
|
|
<p>
|
|
When memory files are created or updated, they're automatically chunked and indexed into a local SQLite database with vector embeddings. This gives the agent semantic search — it can find relevant memories even when the exact keywords don't match. Searching for "that API we integrated" will find the entry about "REST endpoint configuration for Stripe webhooks" because the vectors capture meaning, not just words.
|
|
</p>
|
|
|
|
<h3>Hybrid Search: The Best of Both Worlds</h3>
|
|
<p>
|
|
Search results are ranked using a <strong>hybrid scoring algorithm</strong>: 70% vector similarity (semantic meaning) blended with 30% BM25 keyword matching (exact term relevance). This means the system excels at both fuzzy conceptual queries and precise keyword lookups. Every search completes in under 100 milliseconds.
|
|
</p>
|
|
|
|
<h3>Pre-Compaction Flush Mechanism</h3>
|
|
<p>
|
|
Clawdbot monitors token usage throughout the session. When the conversation reaches approximately 4,000 tokens below the compaction threshold, a <strong>silent flush turn</strong> is injected. The agent writes all accumulated context to memory files, responds with <code>NO_REPLY</code>, and the user never sees this happen. Compaction then proceeds with all data safely persisted. It's the safety net that catches everything.
|
|
</p>
|
|
|
|
<h3>Production Stats</h3>
|
|
|
|
<div class="stats-grid">
|
|
<div class="stat-card">
|
|
<span class="stat-value">35+</span>
|
|
<span class="stat-label">Memory Files</span>
|
|
</div>
|
|
<div class="stat-card">
|
|
<span class="stat-value">121+</span>
|
|
<span class="stat-label">Search Chunks</span>
|
|
</div>
|
|
<div class="stat-card">
|
|
<span class="stat-value"><100ms</span>
|
|
<span class="stat-label">Search Speed</span>
|
|
</div>
|
|
<div class="stat-card">
|
|
<span class="stat-value">~$0.50</span>
|
|
<span class="stat-label">Cost / Month</span>
|
|
</div>
|
|
</div>
|
|
|
|
<p style="text-align:center; color:#888; font-size:0.88rem;">Measured in production on Jake's Clawdbot instance. Zero data loss across months of daily use.</p>
|
|
|
|
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 4: WHAT GETS INSTALLED -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>What Gets Installed</h2>
|
|
|
|
<p>The installer is modular — you choose what you want. The core memory system is always installed; everything else is optional and additive.</p>
|
|
|
|
<div class="feature-section core">
|
|
<h3>🧠 Core Memory System <span class="badge core-badge">Always Installed</span></h3>
|
|
<ul>
|
|
<li><strong><code>memory/</code> directory</strong> with date-based templates for daily logging</li>
|
|
<li><strong>SQLite vector search index</strong> — local, fast, no external database needed</li>
|
|
<li><strong>Hybrid search</strong> — 70% semantic vector similarity + 30% BM25 keyword matching</li>
|
|
<li><strong>Pre-compaction auto-flush</strong> — silent save triggered before compaction fires</li>
|
|
<li><strong>Agent instructions in <code>AGENTS.md</code></strong> — teaches the agent how to use memory properly</li>
|
|
<li><strong>Non-destructive config patch</strong> — adds memory tools to Clawdbot without touching your existing setup</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="feature-section optional">
|
|
<h3>📂 Organization System <span class="badge optional-badge">Optional</span></h3>
|
|
<ul>
|
|
<li><strong>Project Quickstart Protocol</strong> — structured templates for kicking off new projects</li>
|
|
<li><strong>Research Intel System</strong> — weekly rotation with automatic compression (current week detailed, previous weeks summarized)</li>
|
|
<li><strong>Project Tracking</strong> — stages, blockers, decisions, and progress for each project</li>
|
|
<li><strong>Contacts Tracker</strong> — people, roles, preferences, and interaction history</li>
|
|
<li><strong>Tag Convention</strong> — consistent naming (<code>#project/name</code>, <code>#decision</code>, <code>#preference</code>) for reliable search</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="feature-section optional">
|
|
<h3>🏗️ Auto-Scaffold <span class="badge optional-badge">Optional</span></h3>
|
|
<p>
|
|
When you start a new project, the agent automatically creates structured memory files — project tracker, research intel, decision log — from templates. You just say "let's start working on X" and the scaffolding appears.
|
|
</p>
|
|
</div>
|
|
|
|
<div class="feature-section optional">
|
|
<h3>🔒 Git Backup <span class="badge optional-badge">Optional</span></h3>
|
|
<p>
|
|
Adds a daily backup habit to the agent's workflow. At the end of each session, the agent commits all memory changes to git and pushes to your private repo. Full version history of everything your agent has ever learned.
|
|
</p>
|
|
</div>
|
|
|
|
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 5: INSTALLATION GUIDE -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>Installation Guide</h2>
|
|
|
|
<img src="install-flow.svg" alt="Installation Flow" class="diagram"/>
|
|
|
|
<h3>One Command to Install</h3>
|
|
|
|
<p>Open your terminal and run:</p>
|
|
|
|
<pre><code>bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh)</code></pre>
|
|
|
|
<p>The installer is interactive and walks you through five questions:</p>
|
|
|
|
<div class="install-step">
|
|
<div class="step-num">1</div>
|
|
<div class="step-text">
|
|
<strong>Choose your embedding provider</strong><br/>
|
|
OpenAI, Gemini, or Local? <span class="recommended">★ Jake recommends: OpenAI (best quality, ~$0.50/mo)</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="install-step">
|
|
<div class="step-num">2</div>
|
|
<div class="step-text">
|
|
<strong>Enter your API key</strong> (if using OpenAI or Gemini)<br/>
|
|
<span class="recommended">★ Paste your key — it's stored locally only</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="install-step">
|
|
<div class="step-num">3</div>
|
|
<div class="step-text">
|
|
<strong>Enable the Organization System?</strong><br/>
|
|
Project tracking, research intel, contacts. <span class="recommended">★ Jake recommends: Yes</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="install-step">
|
|
<div class="step-num">4</div>
|
|
<div class="step-text">
|
|
<strong>Enable Auto-Scaffold?</strong><br/>
|
|
Auto-create project files when you start new work. <span class="recommended">★ Jake recommends: Yes</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="install-step">
|
|
<div class="step-num">5</div>
|
|
<div class="step-text">
|
|
<strong>Enable Git Backup?</strong><br/>
|
|
Daily commits of all memory changes. <span class="recommended">★ Jake recommends: Yes (requires git repo)</span>
|
|
</div>
|
|
</div>
|
|
|
|
<h3>After Installation</h3>
|
|
|
|
<p>Restart the Clawdbot gateway to pick up the new configuration:</p>
|
|
|
|
<pre><code>clawdbot gateway restart</code></pre>
|
|
|
|
<p>Then test it — just ask your agent:</p>
|
|
|
|
<pre><code>"What did we work on today?"</code></pre>
|
|
|
|
<p>If you've been chatting before the install, the agent will start building memory from this point forward. Within one session, it'll be writing to disk automatically.</p>
|
|
|
|
<h3>Embedding Provider Comparison</h3>
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>Provider</th>
|
|
<th>Model</th>
|
|
<th>Quality</th>
|
|
<th>Speed</th>
|
|
<th>Cost</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><strong>OpenAI ⭐</strong></td>
|
|
<td>text-embedding-3-small</td>
|
|
<td>Excellent</td>
|
|
<td>~50ms</td>
|
|
<td>~$0.50/mo</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Gemini</strong></td>
|
|
<td>text-embedding-004</td>
|
|
<td>Very Good</td>
|
|
<td>~80ms</td>
|
|
<td>Free tier available</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>Local</strong></td>
|
|
<td>all-MiniLM-L6-v2</td>
|
|
<td>Good</td>
|
|
<td>~20ms</td>
|
|
<td>Free (CPU only)</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p style="font-size: 0.88rem; color: #888;">Cost estimates based on typical usage (~100 memory operations/day). Local option requires no API key but has slightly lower semantic accuracy.</p>
|
|
|
|
<div class="page-footer">Clawdbot Memory System v2.0 | github.com/BusyBee3333/clawdbot-memory-system</div>
|
|
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
<!-- PAGE 6: THE SEAMLESS EXPERIENCE -->
|
|
<!-- ═══════════════════════════════════════════════ -->
|
|
|
|
|
|
<h2>The Seamless Experience</h2>
|
|
|
|
<p>The best part of the memory system is that <strong>you don't have to do anything</strong>. From your perspective, you just chat normally. Everything happens in the background.</p>
|
|
|
|
<div class="seamless-point">
|
|
<div class="icon">💬</div>
|
|
<div class="text"><strong>You chat normally.</strong> No special commands, no "save this" or "remember that." Just talk to your agent like you always do.</div>
|
|
</div>
|
|
|
|
<div class="seamless-point">
|
|
<div class="icon">✍️</div>
|
|
<div class="text"><strong>Agent writes memory in the background.</strong> Throughout your conversation, the agent is quietly writing decisions, preferences, project updates, and context to disk. You'll occasionally see brief tool calls flash by — that's memory being saved.</div>
|
|
</div>
|
|
|
|
<div class="seamless-point">
|
|
<div class="icon">🔍</div>
|
|
<div class="text"><strong>Agent searches memory automatically.</strong> When you ask about something from a previous session, the agent runs a semantic search before answering. It pulls up relevant context from days, weeks, or months ago — without you asking it to.</div>
|
|
</div>
|
|
|
|
<div class="seamless-point">
|
|
<div class="icon">🛡️</div>
|
|
<div class="text"><strong>Agent flushes before compaction.</strong> When the session is running long and compaction is imminent, the system silently triggers a save. Everything is persisted before any context is lost. You never see this happen.</div>
|
|
</div>
|
|
|
|
<div class="seamless-point">
|
|
<div class="icon">🪄</div>
|
|
<div class="text"><strong>It just works.</strong> Three weeks from now, you'll say "what was that thing we discussed about the database migration?" and your agent will pull up the exact details. No re-explaining. No lost context. It just knows.</div>
|
|
</div>
|
|
|
|
<h3>Where the Edges Are</h3>
|
|
|
|
<p>We believe in being honest about limitations. Here's where you might notice rough edges:</p>
|
|
|
|
<div class="limitation">
|
|
<strong>First session after install:</strong> The agent has no prior memories yet. It starts building from scratch. Give it a session or two and it'll have a solid knowledge base.
|
|
</div>
|
|
|
|
<div class="limitation">
|
|
<strong>Very rapid-fire sessions:</strong> If you send 50 messages in 2 minutes, the agent might batch-write to memory rather than writing after every single message. Nothing is lost — it's just slightly delayed.
|
|
</div>
|
|
|
|
<div class="limitation">
|
|
<strong>Cross-agent memory:</strong> Memory is per-Clawdbot-instance. If you use multiple AI providers or multiple Clawdbot installations, each has its own memory. (We're exploring sync in a future version.)
|
|
</div>
|
|
|
|
<div class="limitation">
|
|
<strong>Embedding costs:</strong> With OpenAI embeddings, expect roughly $0.50/month for typical daily use. Gemini has a free tier. Local embeddings are completely free but slightly less accurate on semantic search.
|
|
</div>
|
|
|
|
<div class="limitation">
|
|
<strong>Not a knowledge base:</strong> The memory system captures what happens in your sessions. It's not designed to store entire codebases or documentation — it's for decisions, preferences, project context, and conversational knowledge.
|
|
</div>
|
|
|
|
<p style="margin-top: 2em; text-align: center; font-size: 1.1rem; color: #6c5ce7; font-weight: 600;">
|
|
Your agent should remember you.<br/>Now it does.
|
|
</p>
|
|
|
|
<div class="page-footer" style="margin-top: 4em;">
|
|
Clawdbot Memory System v2.0 | github.com/BusyBee3333/clawdbot-memory-system<br/>
|
|
<span style="font-size: 0.7rem; color: #bbb;">© 2026 Jake Shore. Open source under MIT License.</span>
|
|
</div>
|
|
|
|
</body>
|
|
</html> |