DOCSEARCHbyAlgolia
Submit Docs

Ars Contexta

repository·main·Indexed 25 days ago

https://github.com/agenticnotetaking/arscontexta

A Claude Code plugin that generates a personalized, research-backed cognitive architecture ('second brain') for AI agents. It uses conversational onboarding to derive a custom folder structure, knowledge graph, and processing pipeline. The system utilizes 16 composable feature blocks and configurable Claude Code hook events (SessionStart, PostToolUse, Stop) to automate methodology, validation, and persistence within a user's specific domain.

Tokens
183.3K
Snippets
156
Records
738
Agent score
80%

What's inside Ars Contexta

  1. Understand the Dunbar Model Architecture

    main

    The system uses Dunbar number layers to determine maintenance cadence, context depth, and agent behavior. This architecture dictates how often a contact should be reached and how much context the agent provides for meetings.

    LayerSizeContact CadenceContext DepthAgent Behavior
    Inner circle~5BiweeklyLast 3 interactions, full contextUrgent neglect alerts, rich pre-meeting briefings
    Close friends~15MonthlyLast 2 interactions, key contextStandard neglect alerts, moderate briefings
    Active network~50QuarterlyLast interaction, headline contextLow-priority neglect alerts, light briefings
    Wider circle~150Semi-annualName and relationship context onlyAwareness-level tracking, no active alerting

  2. Understand module dependency resolution via topological sort

    main

    Ars Contexta uses topological sort on a Directed Acyclic Graph (DAG) to resolve module dependencies. This process automatically determines a valid initialization order and identifies all transitive requirements. The system is structured in layers to guarantee acyclicity:

    1. Foundation modules (e.g., yaml-schema, wiki-links): Have no dependencies.
    2. Convention modules (e.g., atomic-notes): Depend on foundation modules.
    3. Automation modules (e.g., processing-pipeline): Depend on convention modules.

    Dependencies always point downward through these layers, ensuring that foundations activate first, followed by conventions, and finally automation.

  4. Navigate the Trading Knowledge System MOCs

    main

    The system uses Map of Content (MOC) files to organize trading intelligence:

    Hub MOC (index.md)

    The entry point for the system. It provides navigation to:

    • [[strategies]]: Rule documentation, drift monitoring, and performance.
    • [[theses]]: Market theses, evidence tracking, and conviction calibration.
    • [[trade-psychology]]: Behavioral patterns and emotional triggers.
    • Supporting analysis for [[sectors]], [[earnings]], and [[risk-management]].

    Domain MOC (strategies.md)

    The accountability layer. It tracks:

    • Active Strategies: Performance metrics (win rate, R/R) and drift status.
    • Strategy Insights: Correlated patterns (e.g., [[conviction-levels-predict-outcome-quality]]).
    • Edge Monitoring: Signals of edge decay (e.g., regime changes).
    • Drift Alerts: Active alerts for rule non-compliance.

  5. Understand the Session Persistence Architecture

    main

    Ars Contexta uses a specific directory structure in ops/ to ensure continuity across /clear commands and session restarts.

    Data Layout:

    • ops/sessions/current.json: Tracks active session state (session_id, start_time, notes_created, notes_modified, discoveries, last_activity).
    • ops/sessions/YYYYMMDD-HHMMSS.json: Archived session records.
    • ops/goals.md: Persistent working memory that survives /clear.
    • ops/config.yaml: Live configuration.

    Session ID: Derived from the CLAUDE_CONVERSATION_ID environment variable, falling back to a timestamp $(date +%Y%m%d-%H%M%S) if unavailable.

  6. Upgrade constraints and safety invariants

    main

    The /upgrade command follows a strict safety model to prevent unauthorized or unobserved system changes:

    • No auto-implementation: The upgrade plan is always presented to the user for review. The system never applies changes without explicit user approval.
    • Advisory nature: All upgrades are advisory; the user maintains full ownership of the skill files.
    • Plugin dependency: The /upgrade command requires the Ars Contexta plugin to function. It relies on the plugin's bundled methodology/ and reference/ directories to evaluate skills against the knowledge base.

  7. Leverage Agent-Native Advantages for Academic Research

    main

    The Ars Contexta methodology provides several agent-native advantages for researchers using structured extraction and cross-source synthesis:

    • Exhaustive Cross-Referencing at Ingest: Automatically connects every new paper/claim to the entire existing vault, surfacing contradictions and cross-discipline connections that exceed human working memory.
    • Stale Synthesis Detection: Continuously monitors the dependency chain. If a claim underlying a synthesis note is updated, contradicted, or enriched, the synthesis note is automatically flagged for review.
    • Replication Status Tracking: Maintains a replication status schema field on every claim. This allows for queries like identifying arguments that rely on unreplicated findings.
    • Methodology-Aware Connection Finding: Enables structured queries across methodology fields (e.g., comparing findings across different paradigms) and flags methodological dependencies where a claim's strength is tied to a single method.
    • Citation Graph Analysis: Maintains a live citation graph to perform impact analysis, such as identifying all claims affected by a retracted paper or verifying the consistency of an argument's citation chain.

  8. Understand Parallel Mode Architecture

    main

    Parallel mode uses a two-phase design to ensure both speed and data integrity:

    1. Phase A (Parallel Processing): Up to 5 concurrent workers are spawned. Each worker processes all 4 phases for a single note. Workers are provided with 'sibling awareness' (titles of other notes in the same batch) to proactively create links during the reflect and reweave phases.
    2. Phase B (Cross-Connect Validation): Once all workers from Phase A have completed, a single subagent is spawned to perform a light validation pass. This subagent checks for sibling connections that might have been missed because a sibling note did not exist yet when a worker was running. It fills any backward link gaps.

    Note: Phase B cannot start until every worker from Phase A has reported back (success or error).

  9. Review deferred features for Ars Contexta

    main

    The reference/open-questions.md document tracks research questions, features deferred to v1.1, and items deferred to v2. This is useful for understanding the current limitations of the system and the planned evolution of the derivation engine and architecture.

    Key areas of future development include:

    • Health Monitoring: A read-only --scan mode for the /health command.
    • Migration: Tools to import Obsidian or Notion collections.
    • Multi-Platform: Support beyond Claude Code.
    • Advanced Heuristics: Richer conversation flow analysis and confidence calibration.
    • Background Processing: 'Sleep-Time Compute' for background maintenance and synthesis.
    • Data Export: Anonymized observation export for system improvement.

  10. Understand the Rethink methodology learning loop

    main

    The {vocabulary.rethink_title} acts as the system's immune system, detecting when outdated assumptions cause friction. The methodology learning loop follows this cycle:

    1. Work happens: Friction is captured as observations or tensions.
    2. Immediate correction: /remember captures immediate fixes.
    3. Accumulation: observations accumulate over time.
    4. Triage & Detection: /{vocabulary.rethink} triages items, detects patterns, and proposes changes.
    5. Evolution: A human approves changes, the system evolves, and friction decreases.

  11. Understand the Derivation Phase (Phase 3)

    main
    The Derivation phase is an internal reasoning process that occurs after user onboarding and conversation. It maps user signals to system dimensions to build a custom configuration. This phase is invisible to the user and consists of several steps: mapping signals to dimensions, cascading resolution based on interaction constraints, deriving vocabulary, deriving personality, and performing a three-pass coherence validation. The goal is to create a system tailored to the user's specific domain, volume, and granularity preferences.

  12. Understand Stigmergic Coordination in Agent Systems

    main

    Ars Contexta uses stigmergy to coordinate ephemeral agent sessions through environmental traces rather than direct messaging. Instead of agents communicating with each other, they modify the vault environment (the 'substrate'), and subsequent agents respond to those modifications.

    Types of Stigmergic Traces

    Traces are categorized into two classes based on their purpose and persistence:

    1. Operational Stigmergy: Temporal traces used to coordinate active work. These include:

      • Queue state: Tracks current processing phases (e.g., current_phase: "reflect").
      • Task files: Accumulate notes and state from specific processing phases.
      • Note: These typically expire once processing is complete.

    2. Knowledge Stigmergy: Compounding traces used to build long-term understanding. These include:

      • Wiki links: Create traversal paths and implement a form of GraphRAG without specialized infrastructure.
      • MOC (Map of Content) updates: Organize notes into higher-level structures.
      • Note: These increase in value as more connections are made.

    The Portability Gradient

    Coordination capability depends on the abstraction layer an agent can access:

    • Foundation-layer (Universal): Plain text files, wiki links, folder structures, and YAML frontmatter. Any LLM with filesystem access can participate.
    • Convention-layer: Naming patterns and quality standards defined in context files.
    • Automation-layer: Hook-triggered responses and validation results.
    • Orchestration-layer: Queue state and multi-agent team coordination.