Skip to content

persistent memory

Jump to bottom
Aryan Iyappan edited this page Apr 28, 2026 · 2 revisions

title: Persistent Memory category: concepts tags: [harness, memory, wiki, knowledge-base, layer-6, claude-obsidian] status: developing created: 2026-04-28 updated: 2026-04-28 sources:

  • "harness-implementation-plan" related:
  • "agentic-harness"
  • "wiki-query-interface"
  • "schema-orchestration" layer: "Layer_6" summary: Layer 6 is the knowledge base substrate every other layer reads and writes. ADR-009 replaced custom WikiKnowledgeBase + Vectra with claude-obsidian skills in GitHub Mode B. Search is LLM-native: hot.md → index.md → pages. provenance: extracted: 0.8 inferred: 0.2 ambiguous: 0.0

Persistent Structured Memory

Origin Principle

Humans have persistent biological memory. Agents don't. Every context window starts fresh. The harness needs an explicit memory layer — a knowledge base that persists across sessions, supports cross-referencing, and enables retrieval. This layer is mandatory. It is the substrate every other layer reads and writes.

ADR-009: claude-obsidian Mode B

The memory layer uses claude-obsidian skills operating in GitHub Mode (Mode B). No custom WikiKnowledgeBase class, no Vectra, no embedding model.

Capability Before (ADR-007) After (ADR-009)
Cross-session memory None hot.md ~500-word cache
Source provenance No tracking .raw/ immutable sources + manifest delta
Repository structure Flat patterns/ dirs Mode B: modules, components, decisions, dependencies, flows
Search Vectra BM25+vector (~80MB model) LLM-native: hot.md → index.md → pages
Lint / health None 8+ category checks
Contradiction flagging None > [!contradiction] callouts
Batch ingest One-at-a-time Delta tracking via manifest
Cross-references Plain links Wikilinks [[Page Name]] + backlinks
Dependencies ~87MB ~50KB skills + optional ollama

Wiki Structure (Mode B)

wiki/
  index.md                # Master catalog
  log.md                  # Append-only operation log
  hot.md                  # Hot cache: ~500-word recent context
  overview.md             # Executive summary
  decisions/              # Architecture Decision Records
  modules/                # Major modules, packages, services
  components/             # Reusable UI or functional components
  dependencies/           # External deps, versions, risk
  flows/                  # Data flows, request paths, auth flows
  sources/                # Summary pages per .raw/ source
  entities/               # People, orgs, products, repos
  concepts/               # Ideas, patterns, frameworks
  meta/                   # Dashboards, lint reports, conventions

Harness Entry Type Mapping

Harness Entry Mode B Location Frontmatter Type
decision wiki/decisions/ decision
success_pattern wiki/modules/ or wiki/components/ module/component with status: mature
failure_pattern wiki/modules/ or wiki/flows/ module/flow with > [!contradiction] callout
spec wiki/decisions/ decision with decision_type: spec
plan wiki/flows/ flow with plan_status
checkpoint wiki/log.md append N/A
review wiki/decisions/ decision with review_*
evolution_event wiki/log.md append N/A

Search: Three Depth Modes

Mode Reads Token Cost When
Quick hot.md + index.md ~1,500 Simple factual lookups
Standard (default) hot.md → index.md → 3-5 pages ~3,000 Most harness decisions
Deep Full wiki + optional web ~8,000+ Synthesis, gap analysis

Write Patterns by Layer

Layer When What Written
1 Spec hardened Decision (hardening choices, ambiguities)
2 Plan approved Decision (planning choices, risks)
3 Checkpoint recorded Evolution event (files changed)
3 Drift detected Failure pattern
3 Execution complete Success pattern
4 Subtask verified Success pattern
4 Subtask failed Failure pattern with > [!contradiction]
5 Observability defined Decision (metric choices)

Extension Event Hooks

Event Wiki Operation
session_start Read hot.md, scaffold wiki if needed
session_shutdown Update hot.md, append to log.md
turn_end Auto-capture decision rationale
spec_hardened Store spec as decision
plan_approved Store plan as flow
subtask_verified Store success pattern
subtask_failed Store failure pattern with contradiction callout

Lint

Runs after every 10-15 writes: orphan pages, dead links, stale claims, missing pages, frontmatter gaps, empty sections, stale index entries. Output: wiki/meta/lint-report-YYYY-MM-DD.md

Dependencies

  • 24 obsidian-wiki skills: npx skills add Ar9av/obsidian-wiki --yes
  • 5 obsidian-skills: npx skills add kepano/obsidian-skills --yes
  • Optional: ollama + nomic-embed-text for DragonScale semantic tiling (>10k entries)

Clone this wiki locally