Agent memory coverage

Type: kb/types/note.md · Status: current

Commonplace realizes agent memory as a file-backed knowledge base with a small command and skill surface. Its durable memory is not a single store. It is the combined system of authored artifacts, generated views, validation commands, review state, and always-loaded routing context that future agents can use inside bounded context.

The requirements come from Designing a Memory System for LLM-Based Agents. This page maps those requirements to the shipped Commonplace system and names the main remaining limits.

Coverage map

Memory requirement Commonplace realization Current limit
Control-plane memory AGENTS.md keeps KB goals, scope, routing, vocabulary, commands, skills, and git conventions in always-loaded context. See control-plane goals. There is no typed on-situation cue index yet.
Direct memory creation Agents and maintainers write notes, reference docs, ADRs, instructions, skills, source ingests, workshop artifacts, validators, and indexes as ordinary files. Promotion decisions are still mostly manual.
Artifact contracts COLLECTION.md defines each collection's register, quality goal, scope, and outbound-linking rules. The type: field points to a type-spec doc with structure, prose guidance, and schema. See collections and types and type loading. Project-specific collections still depend on users defining good contracts.
Import and evidence Source snapshots, ingest reports, conversion tooling, and workshops preserve external material and stage it for durable artifacts. Broad session-trace capture, redaction, retention, and replay are not shipped.
Discoverability Titles, descriptions, tags, directory indexes, generated indexes, key-index pointers, rg, file paths, and skill metadata provide progressive routing surfaces. Ranking and quality scoring remain underdeveloped.
Composability Link prose, collection-owned link labels, claim titles, definitions, and indexes preserve relationships among artifacts. Automated connection discovery is report-based, not continuously maintained.
Trust Script validation checks frontmatter, links, enum values, required sections, and template headings. Review gates add semantic checks with stored acceptance state. See review system architecture. Behavioral faithfulness and activation effects are not measured as first-class metrics.
Storage roles Authored markdown is the source of truth; generated indexes are rebuildable; reports are operational artifacts; review state lives in SQLite. See storage. Compiled behavior-facing views need stronger source-of-truth and regeneration rules.
Activation Always-loaded AGENTS.md, on-demand file reads, and on-invoke skills load relevant memory into agent work. Situation-triggered activation remains future work.
Prose-to-code promotion Repeated procedures and stable rules can become instructions, skills, type specs, schemas, review gates, validators, scripts, or commands. There is no mature candidate queue that scores future value against maintenance cost.
Lifecycle Status fields, validation failures, review staleness, generated-index refresh, workshop closure, and log review provide partial lifecycle handling. Retirement, supersession, relaxation, recurrence tracking, and scheduled lifecycle work are incomplete.
Native work environment Markdown, git, shell commands, .claude/skills/, .agents/skills/, and package commands let Claude Code, Codex, and similar agents inspect and edit memory where they already work. See architecture and instruction generation. Harness-specific execution policy differs across tools.
Reusable memory distribution commonplace-init installs reusable methodology under kb/commonplace/ while leaving user collections project-owned. Shared types stay in kb/types/; promoted skills are symlinked into harness skill directories. Local project authority and shipped-library upgrades still require operator judgment.

Boundary

Commonplace is strongest today as a directly authored, quality-controlled, IDE-compatible memory substrate. It covers artifact contracts, discoverability, composability, validation, review, and source-of-truth boundaries well.

It is weaker as an autonomous learning system. Automated session-trace extraction, candidate promotion queues, on-situation cue activation, behavioral uptake tests, and mature lifecycle scheduling remain design work, not shipped capability.

  • Commonplace architecture — contains: installed layout, shipped library, user collections, and skill discovery surfaces
  • Storage — contains: authored markdown, generated indexes, reports, and review SQLite state
  • Control-plane goals — contains: always-loaded KB goals and routing context in AGENTS.md
  • Collections and types — implements: collection contracts plus type contracts
  • Type loading — implements: path-valued type pointers and authoring-time contract loading
  • Review system architecture — implements: semantic review, provenance, acceptance, and stale-pair detection
  • Instruction generation — implements: scaffold generation and multi-harness skill installation

Relevant Notes: