Skip to content

Inspirations

Jump to bottom
Eugene Naumov edited this page May 11, 2026 · 1 revision

Inspirations

agent-notes draws from two key projects in the AI-assisted development space.

Karpathy's LLM Wiki

Source: gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

Andrej Karpathy proposed using LLMs to maintain persistent personal knowledge wikis. The core insight: instead of re-deriving knowledge from scratch on every query (traditional RAG), build a compounding wiki artifact that accumulates synthesis over time.

Three-layer architecture

  1. Raw sources (immutable) — articles, codebases, documents the LLM reads but never modifies
  2. The wiki (LLM-maintained) — structured markdown pages with summaries, entity pages, concept pages, cross-references
  3. The schema (configuration) — rules for how the LLM maintains the wiki (structure, conventions, workflows)

Three operations

  • Ingest: Read source material, create summary pages, update entity/concept pages, cross-reference everything, log the activity
  • Query: Search wiki pages, synthesize answers with citations. Valuable answers filed back as new pages, compounding knowledge
  • Lint: Detect contradictions, stale claims, orphan pages, missing cross-references, data gaps

Key quote

"The wiki is a persistent, compounding artifact."

"You're in charge of sourcing, exploration, and asking questions. The LLM does all the grunt work — summarizing, cross-referencing, filing, and bookkeeping."

What agent-notes implements

The Wiki memory mode is a direct implementation of Karpathy's pattern:

  • raw/ directory for immutable source material (chunked into manageable files)
  • wiki/ directory with typed pages (sources, concepts, entities, synthesis)
  • index.md for content-oriented catalog
  • log.md for append-only operation history
  • memory ingest for the ingest operation
  • memory query for the query operation
  • memory lint for the lint operation
  • wiki-compiler agent for the compile step (reading raw sources, writing rich Wikipedia-style pages)
  • Confidence levels (high/medium/low) on compiled pages
  • Cross-referencing via [[wikilinks]]

Matt Pocock's Skills

Source: github.com/mattpocock/skills

Matt Pocock's "Skills for Real Engineers" collection pioneered the pattern of composable AI agent workflows for practical software engineering. Published as shareable Claude Code skills, they address common failure modes in AI-assisted development through deliberate, structured processes.

Key concepts adopted

Skills as on-demand workflows: Each skill is a SKILL.md file that loads specialized instructions into the agent's context. agent-notes adopted this pattern directly — skills are invoked with /skill-name and provide structured workflows for specific tasks.

CONTEXT.md: A shared domain language document that reduces ambiguity between human and AI. Establishes ubiquitous language (Evans, Domain-Driven Design) so conversations use consistent terminology. agent-notes includes /setup-project-context for bootstrapping this.

Session-oriented thinking: Treating each coding session as a discrete unit with its own context, decisions, and outcomes. This inspired agent-notes' per-project session scoping where each project gets isolated memory.

Tight feedback loops: Small, deliberate steps with verification at each stage. Manifested in agent-notes' task pipelines (explore, implement, review, verify).

Domain-Driven Design influence: Using ubiquitous language so agents and developers share the same mental model. Reduces token usage and improves naming consistency.

Skills directly inspired by Pocock's work

agent-notes skill Pocock original Adaptation
/tdd tdd RED-GREEN-REFACTOR via vertical slices
/grill-me grill-me Interview relentlessly about plan/design
/grill-with-docs grill-with-docs Challenge plan against domain model
/improve-codebase-architecture improve-codebase-architecture Find deepening opportunities
/zoom-out zoom-out Higher-level map of unfamiliar code
/debugging-protocol diagnose Systematic debugging with feedback loop
/refactoring-protocol — Safe refactoring (inspired by philosophy)
/caveman caveman Ultra-compressed communication
/setup-project-context setup-matt-pocock-skills Bootstrap CONTEXT.md glossary

The Synthesis

agent-notes combines both approaches into a unified system:

  • Pocock's model for process memory — decisions, patterns, mistakes, session logs. Answers: "What did we learn? What worked? What failed? Why did we choose this?"

  • Karpathy's model for domain memory — compiled knowledge pages that compound over time. Answers: "How does this work? What are the facts? What are the relationships?"

The per-project scoping applies to both: each project gets its own isolated vault, whether for session-oriented Obsidian notes or wiki-style knowledge compilation. The lead orchestrates, the agents write, and the wiki compounds.

Clone this wiki locally