Ars Contexta

Type: ../types/agent-memory-system-review.md · Status: current · Tags: trace-derived

Ars Contexta is Heinrich's Claude Code plugin for generating agent-operated knowledge systems from a short derivation conversation. The reviewed repo is not mainly a runtime library; it is a packaged methodology and system-definition bundle: setup skills, generated-vault templates, platform hook scripts, command skills, presets, and a large linked methodology graph. Its central memory-system claim is that an agent can be given a local markdown vault whose folder layout, context file, processing commands, hooks, queue state, and self-evolution records are all derived from research-backed principles and then consumed by future Claude Code sessions.

Repository: https://github.com/agenticnotetaking/arscontexta

Reviewed revision: 2acfd5cc4473c4d06c46be63df748e77e00e2746

Core Ideas

The plugin is a system-definition artifact factory. The plugin manifest describes Ars Contexta as a Claude Code plugin with a conversational derivation engine, 15 kernel primitives, 26 commands, 17 feature blocks, and 3 presets (plugin.json, marketplace.json). The setup skill makes this explicit: it detects platform capability, asks the user about their domain, resolves dimensions and vocabulary, writes ops/derivation.md first, then generates the folder structure, context file, self files, templates, runtime manifest, skills, hooks, manuals, queue, reminders, and marker file (skills/setup/SKILL.md). Those generated files are system-definition artifacts because Claude Code, hooks, and generated skills consume them with instruction, configuration, validation, routing, or automation force.

The retained architecture separates self, notes, and ops. The README and three-spaces.md define three spaces: self/ for agent identity and orientation, the domain-named notes space for durable knowledge, and ops/ for derivation records, config, reminders, observations, sessions, health, methodology, and queues (README.md, reference/three-spaces.md). This is a strong artifact-contract move: domain notes are knowledge artifacts when used as evidence or reference; self/, CLAUDE.md, ops/config.yaml, ops/derivation-manifest.md, hooks, and skills become stronger behavior-shaping surfaces when loaded by agents or scripts.

The kernel defines invariant primitives, not just starter folders. reference/kernel.yaml names primitives for markdown/YAML, wiki links, MOC hierarchy, tree injection, descriptions, schema enforcement, session rhythm, semantic search, discovery-first creation, operational learning, task stack, methodology folder, and session capture, with enforcement levels and validation checks (reference/kernel.yaml). interaction-constraints.md adds cross-dimension coherence rules, including blocked combinations such as full automation on platforms without hooks and heavy processing without pipeline skills (reference/interaction-constraints.md). The generated system is therefore a bundle of executable conventions with a validation model, not a neutral note template.

Generated command skills are the operational API. Ars Contexta ships plugin-level skills such as setup, help, health, ask, architect, add-domain, reseed, and upgrade, plus generated processing skills such as reduce, reflect, reweave, verify, validate, seed, ralph, pipeline, tasks, stats, graph, next, learn, remember, rethink, and refactor (skills/, skill-sources/). These skills are mostly prose instructions with tool permissions, runtime config reads, and prescribed file mutations. The representational form is prose plus symbolic YAML/JSON/Bash; the behavioral authority is high because Claude Code invokes them as commands.

The queue and fresh-context pattern make processing stateful without a service. /pipeline seeds a source, runs /reduce, then uses /ralph to process extracted tasks through create, reflect, reweave, and verify phases, with task state in ops/queue/ (skill-sources/pipeline/SKILL.md, skill-sources/ralph/SKILL.md). /ralph requires a fresh subagent for every task phase; the lead session only reads queue state, spawns work, parses handoff, and advances the queue. The queue files are operational retained artifacts: they coordinate future action, but they are not intended to become permanent knowledge.

Hooks convert routine instruction into event-driven infrastructure. The plugin-level hook config installs SessionStart orientation and PostToolUse Write validation/auto-commit hooks (hooks/hooks.json). session-orient.sh injects a tree, surfaces previous session state, goals, identity, recent methodology notes, maintenance thresholds, and optional workboard reconciliation; write-validate.sh warns on missing description/topics/frontmatter; auto-commit.sh stages and commits all pending changes when git automation is enabled (session-orient.sh, write-validate.sh, auto-commit.sh). The source also documents project hook generation with a Stop hook, but the checked-in plugin hook config does not include Stop, and the session-capture template records metadata rather than a full transcript (platforms/claude-code/hooks/session-capture.sh.template).

The methodology graph is both evidence and product DNA. The repo contains hundreds of methodology notes under methodology/, plus references that map claims to generated behavior (methodology/, reference/methodology.md). These are knowledge artifacts when queried via /ask or read as rationale. They become system-definition inputs when setup, architect, reseed, and generated context use them to choose dimensions, warnings, feature blocks, and vocabulary.

Comparison with Our System

Dimension	Ars Contexta	Commonplace
Primary purpose	Generate a domain-specific Claude Code-operated vault	Operate and document a methodology KB as the reusable framework
Storage substrate	Local markdown/YAML plus Claude plugin files, Bash hooks, queue JSON/YAML, git	Local markdown/YAML plus Python CLI, schemas, generated indexes, review records, git
Main retained surfaces	Generated CLAUDE.md, self/, domain notes, ops/, skills, hooks, templates, methodology notes	Typed KB notes, collection contracts, type specs, instructions, skills, validators, indexes
Authority model	Generated files directly instruct, validate, orient, route, and automate Claude Code sessions	Artifact type, collection contracts, CLI validation, review gates, and skills define authority
Lineage	ops/derivation.md, runtime manifest, methodology claims, generated_from fields, git	Frontmatter, source snapshots, review metadata, generated index provenance, git
Activation	Claude Code plugin commands, auto-loaded context file, hooks, skill invocation, queue orchestration	Agent navigation, local skills, Python commands, authored links, validation/review workflows
Evolution	/remember, /rethink, /architect, /reseed, observations, tensions, methodology folder	Notes, ADRs, review bundles, fix/review systems, skill updates, indexes, validation

Ars Contexta is historically close to commonplace: both assume local files, markdown, explicit links, validation, generated indexes/views, skills, and agent-native navigation. The difference is product posture. Commonplace is the methodology KB and shipped tooling for maintaining such KBs; Ars Contexta is a Claude Code plugin that tries to derive a complete user-specific instance from conversation.

Ars Contexta is more ambitious on first-run generation. It tries to create a full context file, command suite, hooks, templates, manual, queue, self-space, and methodology folder in one derivation flow. Commonplace is more conservative about artifact contracts: collection-local type specs, validation commands, and review workflows make explicit what each artifact is allowed to do. Ars Contexta has similar concepts, but much of its authority lives in generated prose skills and context-file sections rather than in deterministic package code.

The systems also diverge on backpressure. Commonplace's review and validation loops mostly operate after artifacts exist. Ars Contexta pushes quality earlier by generating pipeline commands and hooks that affect note creation, orientation, and persistence. The tradeoff is that some documented promises are stronger than the inspected implementation: automatic transcript capture and Stop-hook persistence are described in setup/platform references, while the active plugin hook config at this commit only wires SessionStart and PostToolUse.

Read-back: both — agents can invoke query/processing skills, and context files plus hooks inject orientation automatically.

Borrowable Ideas

Derivation manifest as runtime vocabulary layer. Ready to borrow where skills must adapt to project vocabulary. Ars Contexta separates human-readable derivation rationale from machine-readable ops/derivation-manifest.md, and generated skills read the manifest at invocation time (skills/setup/SKILL.md). Commonplace could use a lighter version for consuming-project installations without cloning every skill per vocabulary.

Rule Zero: methodology notes as canonical operational spec. Ready to borrow in workshop form. /remember writes actionable directives into ops/methodology/, and /rethink treats that folder as the source of drift checks (skill-sources/remember/SKILL.md, skill-sources/rethink/SKILL.md). Commonplace already has instructions and notes; the borrowable piece is an explicit "operational spec from observed friction" layer before promotion to shipped instructions.

Session orientation as compiled context. Ready to borrow selectively. Ars Contexta's SessionStart hook compiles file tree, goals, identity, methodology snippets, and maintenance signals into the next session's opening context. Commonplace should keep generated indexes and validation reports as canonical sources, but a small compiled orientation view for active workshops could reduce rediscovery.

Fresh-context phase orchestration with handoff blocks. Needs a concrete high-volume use case. /ralph is a useful pattern for avoiding context contamination during multi-phase processing, but it is expensive and assumes a Task/subagent-capable harness. Commonplace should use it for large ingest/review batches, not for ordinary note edits.

Do not borrow plugin auto-commit as-is. The active auto-commit.sh uses git add -A and commits all pending changes. That fits a single-user generated vault poorly enough already, and it conflicts with commonplace's multi-agent staging discipline. The stronger borrow is the intent: deterministic persistence belongs in infrastructure, but staging scope must be precise.

Trace-derived learning placement

Trace source. Ars Contexta qualifies as trace-derived learning through its /remember --mine-sessions path. The qualifying traces are session transcripts or session files under ops/sessions/, plus explicit or contextual correction signals in the current conversation. The automatic trace-capture substrate is incomplete at this commit: the platform docs and setup skill describe Stop-hook session capture, but the checked-in plugin hooks omit Stop, and the session-capture template stores JSON metadata rather than a full transcript.

Extraction. /remember extracts user corrections, repeated redirections, workflow breakdowns, agent confusion, undocumented decisions, and escalation patterns. It classifies findings as either actionable methodology learning or observations requiring more accumulation, deduplicates against existing ops/methodology/ and ops/observations/, writes methodology notes or observations, and marks sessions as mined when session files have frontmatter (skill-sources/remember/SKILL.md).

Storage substrate. Raw or semi-raw session state lives in ops/sessions/. Pending signals live in ops/observations/ and ops/tensions/. Distilled behavioral guidance lives in ops/methodology/. Stable generated instructions live in the context file, generated skills, hook scripts, and config files.

Representational form. Raw traces are expected to be prose transcripts or session records. Observations, tensions, and methodology notes are prose with YAML frontmatter. Config, queue, and manifest files are symbolic YAML/JSON. Hooks and graph/query scripts are executable symbolic artifacts. There is no inspected mechanism that trains weights or stores learned embeddings as the operative learned state.

Lineage. /remember records source: session-mining and session_source for mined methodology notes or observations, and marks sessions as mined. /rethink can then promote, implement, archive, or keep findings pending. The lineage is sufficient at the note/session level, but not at the exact transcript-span or generated-instruction-fragment level.

Behavioral authority. Session transcripts and observations are knowledge artifacts: they serve as evidence, explanation, and candidate signal. Methodology notes in ops/methodology/ are system-definition artifacts because Rule Zero makes them canonical behavioral directives for future agents and meta-skills. Context-file updates, skills, hooks, and config edits produced by /rethink, /architect, or /reseed are stronger system-definition artifacts because they instruct, validate, route, configure, or automate later work.

Scope and timing. The scope is per generated vault and per project. Timing is staged: traces accumulate during sessions, /remember --mine-sessions or contextual /remember distills them, /rethink detects patterns, and later context or configuration changes stabilize recurring lessons.

Survey placement. On the trace-derived survey, Ars Contexta belongs in the file-native operational-friction-to-methodology family. It strengthens the survey's distinction between raw traces as evidence and promoted instructions as behavior-changing artifacts, while also showing a common implementation gap: documentation may claim automatic session mining before the actual capture hook preserves enough trace content.

Curiosity Pass

• Ars Contexta is strongest as a methodology-to-system compiler, not as a conventional app. Most behavior lives in Markdown skills, generated context, hook scripts, and file conventions.
• The generated system is intentionally maximal: full automation, queue, methodology folder, session capture, graph scripts, and many commands from day one. That reverses older "grow only from friction" logic in favor of "ship complete, opt down."
• The active plugin hook config is less complete than the setup and platform references. Reviewers should distinguish implemented plugin hooks from generated-project hook instructions.
• The repo's own methodology notes are historically important because many of commonplace's current concepts have close relatives here: three spaces, operational learning, hooks as habits, title-as-claim, fresh context per phase, and notes as agent memory.
• The risk is authority sprawl. A generated vault can have behavior-changing rules in CLAUDE.md, self/, ops/methodology/, skill files, hook scripts, templates, config, and queue state. Without validation, agents may not know which surface wins.

What to Watch

• Whether future releases add a real Stop hook or transcript API integration that captures full session traces rather than only session metadata.
• Whether generated skills move from prose-only workflows toward tested scripts or package code for queue migration, validation, hook merging, and graph analysis.
• Whether derivation outputs carry stronger generated-from metadata and per-section lineage back to methodology claims and user signals.
• Whether /rethink and /architect gain deterministic drift checks or remain mostly agent-mediated judgment loops.
• Whether auto-commit becomes scoped enough for multi-agent repositories, or remains a single-operator convenience.
• Whether Ars Contexta stabilizes a public generated-vault schema that other tools can inspect without reading the full generated CLAUDE.md.

---

Relevant Notes:

• Retained artifact - defined-in: Ars Contexta stores behavior-shaping state across context files, skills, hooks, queues, and methodology notes.
• Knowledge artifact - defined-in: methodology claims, session records, observations, and domain notes often advise or evidence later action.
• System-definition artifact - defined-in: generated CLAUDE.md, skills, hooks, config, and methodology directives instruct or automate future agents.
• Behavioral authority - defined-in: the same Markdown substrate can advise, instruct, validate, or configure depending on its consumer path.
• Workshop - compares-with: Ars Contexta's ops/ layer keeps temporal queues, sessions, observations, and health state out of durable notes.
• Trace-derived learning techniques in related systems - source-inspected placement: session/friction traces can become methodology directives and later context changes.