Skip to content

Commit dfc79a2

Browse files
nicoloboschinicoloboschi
committed
docs: add Concepts page covering banks, pages, memories, mental models
Walks through the agent's mental model end-to-end: a personal wiki (knowledge pages) backed by a stream of raw memories, both held in a Hindsight bank, configured via bank-template.json (mental models + directives + dispositions), and refreshed every session via the retain → consolidate → reflect loop. Surfaced from the home page (callout under "How it works"), the header nav, and the footer.
1 parent 09d51f0 commit dfc79a2

4 files changed

Lines changed: 385 additions & 1 deletion

File tree

‎website/src/components/Footer.astro‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ const link = (p: string) => `${base.replace(/\/$/, '')}/${p.replace(/^\//, '')}`
1717
</span>
1818
</div>
1919
<div class="flex flex-wrap gap-x-6 gap-y-2">
20+
<a href={link('/concepts')} class="hover:text-ink-900">Concepts</a>
2021
<a href={link('/agents')} class="hover:text-ink-900">Agents</a>
2122
<a href={link('/harnesses')} class="hover:text-ink-900">Harnesses</a>
2223
<a

‎website/src/components/Header.astro‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ const link = (p: string) => `${base.replace(/\/$/, '')}/${p.replace(/^\//, '')}`
44
55
const nav = [
66
{ href: link('/'), label: 'Home' },
7+
{ href: link('/concepts'), label: 'Concepts' },
78
{ href: link('/agents'), label: 'Agents' },
89
{ href: link('/harnesses'), label: 'Harnesses' },
910
{ href: link('/quickstart'), label: 'Quick start' },

‎website/src/pages/concepts.astro‎

Lines changed: 353 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,353 @@
1+
---
2+
import Layout from '../layouts/Layout.astro';
3+
import CodeBlock from '../components/CodeBlock.astro';
4+
5+
const base = import.meta.env.BASE_URL;
6+
const link = (p: string) => `${base.replace(/\/$/, '')}/${p.replace(/^\//, '')}`;
7+
---
8+
9+
<Layout
10+
title="Concepts"
11+
description="How self-driving agents work: memory banks, knowledge pages (the agent's wiki), memories, mental models, directives, and dispositions."
12+
>
13+
<!-- Hero -->
14+
<section class="border-b border-ink-200 bg-white">
15+
<div class="mx-auto max-w-4xl px-6 py-12">
16+
<p class="text-sm font-medium uppercase tracking-wide text-accent-600">
17+
Concepts
18+
</p>
19+
<h1 class="mt-2 text-3xl font-bold text-ink-900 sm:text-4xl">
20+
How self-driving agents work
21+
</h1>
22+
<p class="mt-3 max-w-2xl text-lg leading-relaxed text-ink-500">
23+
Each agent has a personal wiki it reads at session start, references during
24+
the chat, and rewrites afterwards. The wiki — plus the raw facts it's
25+
distilled from — lives in <a class="text-accent-600 hover:underline" href="https://github.com/vectorize-io/hindsight" target="_blank" rel="noopener">Hindsight</a>,
26+
the memory backend.
27+
</p>
28+
</div>
29+
</section>
30+
31+
<!-- Mental model -->
32+
<section class="border-b border-ink-200 bg-ink-50">
33+
<div class="mx-auto max-w-4xl px-6 py-12">
34+
<h2 class="text-2xl font-semibold text-ink-900">The mental model</h2>
35+
<p class="mt-2 text-ink-600">
36+
Two layers, both per-agent:
37+
</p>
38+
39+
<div class="mt-6 grid gap-4 md:grid-cols-2">
40+
<div class="rounded-xl border border-ink-200 bg-white p-5">
41+
<h3 class="text-lg font-semibold text-ink-900">📒 Knowledge pages</h3>
42+
<p class="mt-1 text-sm text-ink-500">The wiki.</p>
43+
<p class="mt-3 text-sm leading-relaxed text-ink-700">
44+
Persistent, editable markdown documents the agent owns. Synthesized from
45+
raw memories. Loaded at session start so the agent walks in already
46+
knowing what it knows.
47+
</p>
48+
</div>
49+
<div class="rounded-xl border border-ink-200 bg-white p-5">
50+
<h3 class="text-lg font-semibold text-ink-900">🧾 Memories</h3>
51+
<p class="mt-1 text-sm text-ink-500">The raw stream.</p>
52+
<p class="mt-3 text-sm leading-relaxed text-ink-700">
53+
Atomic facts retained during conversations or ingested from documents.
54+
Searchable, durable, never deleted. Pages are how they get distilled
55+
into something an agent can quickly load and reason over.
56+
</p>
57+
</div>
58+
</div>
59+
60+
<p class="mt-6 text-sm leading-relaxed text-ink-600">
61+
Think of memories as a journal and pages as the wiki entries the agent
62+
keeps writing from that journal. Both live in the agent's <em>bank</em> —
63+
its private container in Hindsight.
64+
</p>
65+
</div>
66+
</section>
67+
68+
<!-- The bank -->
69+
<section class="border-b border-ink-200 bg-white">
70+
<div class="mx-auto max-w-4xl px-6 py-12">
71+
<h2 class="text-2xl font-semibold text-ink-900">The bank: one per agent</h2>
72+
<p class="mt-2 text-ink-600">
73+
A bank is the top-level container in Hindsight. Everything below is scoped
74+
to it — pages, memories, directives, dispositions. When the install CLI
75+
binds an agent to a harness, what it really binds is a <em>bank ID</em>.
76+
</p>
77+
78+
<div class="mt-6 grid gap-3 sm:grid-cols-2">
79+
{[
80+
{ k: 'Reflect mission', v: 'How the agent should synthesize what it learns into pages.' },
81+
{ k: 'Retain mission', v: 'What kinds of facts the agent should extract from conversations.' },
82+
{ k: 'Knowledge pages', v: 'The wiki the agent maintains.' },
83+
{ k: 'Memories', v: 'Raw facts retained over time.' },
84+
{ k: 'Directives', v: 'High-priority rules surfaced at every session start.' },
85+
{ k: 'Dispositions', v: 'Personality traits that bias retention and reflection.' },
86+
].map((row) => (
87+
<div class="rounded-lg border border-ink-200 bg-ink-50 p-3">
88+
<div class="text-xs font-semibold uppercase tracking-wide text-ink-500">
89+
{row.k}
90+
</div>
91+
<p class="mt-1 text-sm text-ink-700">{row.v}</p>
92+
</div>
93+
))}
94+
</div>
95+
</div>
96+
</section>
97+
98+
<!-- Pages -->
99+
<section class="border-b border-ink-200 bg-ink-50">
100+
<div class="mx-auto max-w-4xl px-6 py-12">
101+
<h2 class="text-2xl font-semibold text-ink-900">Knowledge pages: the wiki</h2>
102+
<p class="mt-2 text-ink-600">
103+
Each page is a markdown document with a title and a body. The agent
104+
treats them like a wiki: read everything at startup, edit during the
105+
conversation, let Hindsight refresh them afterwards.
106+
</p>
107+
108+
<p class="mt-6 text-sm font-semibold text-ink-700">REST surface</p>
109+
<div class="mt-2 space-y-3">
110+
<CodeBlock
111+
lang="bash"
112+
code={`# List all pages in the bank
113+
GET /v1/default/banks/{bank}/knowledge/pages
114+
115+
# Read a page
116+
GET /v1/default/banks/{bank}/knowledge/pages/{page_id}
117+
118+
# Create
119+
POST /v1/default/banks/{bank}/knowledge/pages
120+
{ "title": "...", "content": "markdown..." }
121+
122+
# Update
123+
PUT /v1/default/banks/{bank}/knowledge/pages/{page_id}
124+
125+
# Delete
126+
DELETE /v1/default/banks/{bank}/knowledge/pages/{page_id}`}
127+
/>
128+
</div>
129+
130+
<p class="mt-6 text-sm leading-relaxed text-ink-600">
131+
Most harnesses don't talk to this REST surface directly — they go through
132+
the Hindsight MCP server (Claude Code) or a plugin (OpenClaw, NemoClaw,
133+
Hermes). The Claude Chat skill is the one exception: it calls the API via
134+
baked-in <code class="rounded bg-ink-100 px-1 py-0.5">curl</code> snippets.
135+
</p>
136+
</div>
137+
</section>
138+
139+
<!-- Mental models -->
140+
<section class="border-b border-ink-200 bg-white">
141+
<div class="mx-auto max-w-4xl px-6 py-12">
142+
<h2 class="text-2xl font-semibold text-ink-900">Mental models: page recipes</h2>
143+
<p class="mt-2 text-ink-600">
144+
You don't write the wiki by hand. You declare which pages should exist
145+
in <code class="rounded bg-ink-100 px-1 py-0.5">bank-template.json</code> as
146+
<em>mental models</em>. Each mental model is a recipe: a name plus a query
147+
Hindsight runs against the bank's memories to populate (and later refresh)
148+
the page.
149+
</p>
150+
151+
<div class="mt-6">
152+
<CodeBlock
153+
lang="json"
154+
code={`{
155+
"mental_models": [
156+
{
157+
"id": "seo-best-practices",
158+
"name": "SEO Best Practices",
159+
"max_tokens": 4096,
160+
"source_query": "What SEO best practices have we observed working? Combine industry standards with what has actually performed in our data.",
161+
"trigger": {
162+
"refresh_after_consolidation": true,
163+
"mode": "delta",
164+
"exclude_mental_models": true,
165+
"fact_types": ["observation"]
166+
}
167+
}
168+
]
169+
}`}
170+
/>
171+
</div>
172+
173+
<p class="mt-6 text-sm leading-relaxed text-ink-600">
174+
The first time the agent installs, the CLI creates one knowledge page
175+
per mental model. After that, Hindsight keeps each page in sync — when
176+
new memories arrive that match the page's query, the page gets refreshed
177+
in the background. The agent never has to babysit it.
178+
</p>
179+
</div>
180+
</section>
181+
182+
<!-- Directives + dispositions -->
183+
<section class="border-b border-ink-200 bg-ink-50">
184+
<div class="mx-auto max-w-4xl px-6 py-12">
185+
<div class="grid gap-8 md:grid-cols-2">
186+
<div>
187+
<h2 class="text-2xl font-semibold text-ink-900">Directives</h2>
188+
<p class="mt-2 text-sm leading-relaxed text-ink-600">
189+
Optional bank-level rules the agent sees alongside its pages. Each
190+
directive has a <code class="rounded bg-ink-100 px-1 py-0.5">name</code>,
191+
<code class="rounded bg-ink-100 px-1 py-0.5">content</code>, and
192+
<code class="rounded bg-ink-100 px-1 py-0.5">priority</code>. Use them
193+
for "always do X before Y" guidance that should colour every
194+
decision, not just the ones a page happens to mention.
195+
</p>
196+
<p class="mt-3 text-sm leading-relaxed text-ink-600">
197+
Example from the SEO bank:
198+
<em>"Data over dogma — prefer observed performance data over industry
199+
best practices."</em>
200+
</p>
201+
</div>
202+
203+
<div>
204+
<h2 class="text-2xl font-semibold text-ink-900">Dispositions</h2>
205+
<p class="mt-2 text-sm leading-relaxed text-ink-600">
206+
Three personality dials (1–5) that bias how the bank retains and
207+
reflects.
208+
</p>
209+
<ul class="mt-3 space-y-2 text-sm leading-relaxed text-ink-700">
210+
<li>
211+
<strong>Empathy</strong> — how generously it interprets ambiguous
212+
user signals.
213+
</li>
214+
<li>
215+
<strong>Skepticism</strong> — how much it distrusts loose claims
216+
before treating them as fact.
217+
</li>
218+
<li>
219+
<strong>Literalism</strong> — how strictly it preserves exact wording
220+
vs paraphrasing.
221+
</li>
222+
</ul>
223+
<p class="mt-3 text-sm leading-relaxed text-ink-600">
224+
A customer-support bank might run high-empathy, low-skepticism. A
225+
research bank might be low-empathy, high-skepticism, high-literalism.
226+
</p>
227+
</div>
228+
</div>
229+
</div>
230+
</section>
231+
232+
<!-- Lifecycle -->
233+
<section class="border-b border-ink-200 bg-white">
234+
<div class="mx-auto max-w-4xl px-6 py-12">
235+
<h2 class="text-2xl font-semibold text-ink-900">Lifecycle of one conversation</h2>
236+
<ol class="mt-6 space-y-5">
237+
{[
238+
{
239+
t: 'Session starts',
240+
b: 'The agent lists every knowledge page in its bank and reads them. Directives and dispositions come along for the ride. By the time you type your first message, the agent already knows what it knows.',
241+
},
242+
{
243+
t: 'Conversation runs',
244+
b: 'When something noteworthy happens — a decision, a preference, a measurement, a correction — the agent retains it as a memory. In harnesses with auto-retain hooks (OpenClaw, NemoClaw, Hermes) this happens automatically; in Claude Chat/Cowork the skill self-retains via curl.',
245+
},
246+
{
247+
t: 'Session ends → Hindsight consolidates',
248+
b: 'New memories get folded into the bank. For each mental model whose trigger fires, Hindsight re-runs its source_query and rewrites the corresponding knowledge page. The page now reflects what was learned.',
249+
},
250+
{
251+
t: 'Next session starts',
252+
b: 'Same flow again — but the wiki the agent loads is already different. That\'s "self-driving": no retraining, no manual curation, just chat and let the loop run.',
253+
},
254+
].map((step, i) => (
255+
<li class="flex gap-4">
256+
<span
257+
class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-accent-500 text-sm font-semibold text-white"
258+
>
259+
{i + 1}
260+
</span>
261+
<div class="flex-1">
262+
<h3 class="font-semibold text-ink-900">{step.t}</h3>
263+
<p class="mt-1 text-sm leading-relaxed text-ink-600">{step.b}</p>
264+
</div>
265+
</li>
266+
))}
267+
</ol>
268+
</div>
269+
</section>
270+
271+
<!-- What lives where -->
272+
<section class="border-b border-ink-200 bg-ink-50">
273+
<div class="mx-auto max-w-4xl px-6 py-12">
274+
<h2 class="text-2xl font-semibold text-ink-900">What lives where</h2>
275+
<p class="mt-2 text-ink-600">
276+
A quick map between the things you write, the things the CLI generates,
277+
and the things the running agent reads.
278+
</p>
279+
280+
<div class="mt-5 overflow-x-auto rounded-xl border border-ink-200 bg-white">
281+
<table class="w-full text-sm">
282+
<thead class="bg-ink-100 text-ink-600">
283+
<tr>
284+
<th class="p-3 text-left font-semibold">You write</th>
285+
<th class="p-3 text-left font-semibold">CLI sets up</th>
286+
<th class="p-3 text-left font-semibold">Agent reads at runtime</th>
287+
</tr>
288+
</thead>
289+
<tbody class="divide-y divide-ink-200">
290+
<tr>
291+
<td class="p-3"><code class="rounded bg-ink-100 px-1 py-0.5">bank-template.json</code></td>
292+
<td class="p-3">A Hindsight bank with that mission, dispositions, and directives</td>
293+
<td class="p-3">— (config, not runtime)</td>
294+
</tr>
295+
<tr>
296+
<td class="p-3"><code class="rounded bg-ink-100 px-1 py-0.5">mental_models[]</code></td>
297+
<td class="p-3">One knowledge page per model</td>
298+
<td class="p-3">All pages, every session start</td>
299+
</tr>
300+
<tr>
301+
<td class="p-3"><code class="rounded bg-ink-100 px-1 py-0.5">.md / .txt</code> seed files</td>
302+
<td class="p-3">Ingested as initial memories</td>
303+
<td class="p-3">Through the pages they get rolled into</td>
304+
</tr>
305+
<tr>
306+
<td class="p-3"><code class="rounded bg-ink-100 px-1 py-0.5">directives[]</code></td>
307+
<td class="p-3">Saved on the bank</td>
308+
<td class="p-3">Loaded alongside pages at startup</td>
309+
</tr>
310+
</tbody>
311+
</table>
312+
</div>
313+
</div>
314+
</section>
315+
316+
<!-- Next -->
317+
<section class="bg-white">
318+
<div class="mx-auto max-w-4xl px-6 py-12">
319+
<h2 class="text-2xl font-semibold text-ink-900">From here</h2>
320+
<div class="mt-5 grid gap-4 sm:grid-cols-3">
321+
<a
322+
href={link('/agents')}
323+
class="rounded-xl border border-ink-200 bg-ink-50 p-5 transition hover:border-accent-300 hover:bg-white"
324+
>
325+
<h3 class="font-semibold text-ink-900">See real banks</h3>
326+
<p class="mt-1 text-sm text-ink-500">
327+
Browse the marketing templates — each one is a fully populated
328+
bank-template.json.
329+
</p>
330+
</a>
331+
<a
332+
href={link('/harnesses')}
333+
class="rounded-xl border border-ink-200 bg-ink-50 p-5 transition hover:border-accent-300 hover:bg-white"
334+
>
335+
<h3 class="font-semibold text-ink-900">Pick a harness</h3>
336+
<p class="mt-1 text-sm text-ink-500">
337+
Each harness exposes the bank to its own runtime — MCP, plugin, or
338+
skill.
339+
</p>
340+
</a>
341+
<a
342+
href={link('/quickstart')}
343+
class="rounded-xl border border-ink-200 bg-ink-50 p-5 transition hover:border-accent-300 hover:bg-white"
344+
>
345+
<h3 class="font-semibold text-ink-900">Quick start</h3>
346+
<p class="mt-1 text-sm text-ink-500">
347+
Install one in a single command and watch the loop run.
348+
</p>
349+
</a>
350+
</div>
351+
</div>
352+
</section>
353+
</Layout>

0 commit comments

Comments
 (0)