Local-First Agentic Systems

Technical Standard: Local-First Agentic Systems via Neuro-Symbolic Reasoning 1. Architectural Philosophy and Design Principles The current reliance on cloud-centric, non-deterministic chat interfaces is architecturally insufficient for industrial-grade autonomy. This standard necessitates a transition from fragile, prompt-based interactions to sovereign, local-first agentic systems governed by rigorous specifications. By establishing "Local-First" execution and "Specification-First" development as foundational pillars, we ensure that decentralized intelligence remains private, verifiable, and decoupled from vendor-specific black boxes. In this paradigm, the system functions as a Semantic Operating System, transforming raw knowledge into actionable, self-verifying software artifacts. Core Principles Synthesis To mitigate the systemic failures of traditional cloud-AI deployments—specifically latency, data exfiltration, and stochastic drift—this standard enforces four primary design principles: * Local-First Sovereignty: Core operations have zero cloud dependency. All inference, vector indexing, and relational logic occur on local hardware, ensuring maximum privacy and operational continuity in offline environments. * Markdown as Source of Truth: All system intelligence is derived from authored content. Markdown files (.md, .sspec) serve as the primary artifacts for both human documentation and machine reasoning, providing a transparent, versionable audit trail. * Selective Reasoning: Large Language Models (LLMs) are utilized only where symbolic logic is insufficient. Systems must prioritize deterministic parsing and reserve stochastic neural processing for high-level synthesis and speculative planning. * Idempotent Ingestion: The ingestion pipeline is engineered so that identical input consistently produces identical structured output. This ensures the reliability of the knowledge graph across repeated processing cycles. The "Specification-First" Mandate We operate under the mandate that code is disposable while specifications are durable. In a neuro-symbolic system, implementation details are transient execution artifacts, whereas the underlying specification defines the system’s invariant intent and constraints. By mandating the generation of comprehensive planning artifacts—such as directed acyclic graphs (DAGs) and execution plans—before implementation begins, we enable the system to verify logic and speculate on architectural alternatives. This ensures that if a codebase deviates from its specification, the system can autonomously regenerate the code to restore alignment with the durable intent. 2. Multi-Layered System Architecture A robust neuro-symbolic system requires a structural hierarchy that strictly separates raw inference from data persistence and autonomous execution. This layered approach ensures a separation of concerns, facilitating the modular upgrade of models or data stores without compromising system integrity. The Seven-Layer Standard (SpecWeave) The standard architecture is organized into the following functional layers: Layer Number / Name Primary Responsibility Functional Components Layer 1: Local Inference Execution of neural models on local hardware. Ollama, qwen2.5-3b, llama3.2-8b, nomic-embed-text. Layer 2: Persistence Management of structured, semantic, and relational data. SQLite, ChromaDB, NetworkX. Layer 3: Speculative Reasoning Generation and evaluation of architectural alternatives. Draft → Verify → Commit pipeline, GBNF enforcement. Layer 4: Neuro-Symbolic KG Integration of neural generation with symbolic validation. Hybrid loop, graph validation, neural revision. Layer 5: Self-Verifying Compiler Multi-gate validation of system specifications. 12-step pipeline, 6 sequential verification gates. Layer 6: A2A/MCP Gateway Inter-agent communication and tool execution. Agent-to-Agent protocol, Model Context Protocol. Layer 7: Interface Visualization of system state and agent federation. Next.js Dashboards, spec explorers, gate monitors. Functional Layer Mapping (Semantic OS Integration) The five stages of the synthScript Semantic OS are integrated into the seven-layer SpecWeave framework to provide a unified lifecycle: * Knowledge Layer: Encompasses SpecWeave Layer 2 (Persistence) and Layer 4 (Neuro-Symbolic KG), ingesting raw data into vector stores and knowledge graphs. * Specification Layer: Operates within SpecWeave Layer 3 (Speculative Reasoning) and Layer 5 (Compiler), producing structured .sspec artifacts from graph state. * Planning Layer: Facilitated by SpecWeave Layer 5, generating execution DAGs and planning documents from the compiled specifications. * Execution Layer: Realized through SpecWeave Layer 6 (A2A/MCP), where tasks are dispatched to agents via managed protocols. * Feedback Layer: Closes the loop by feeding execution artifacts back into Layer 4 (KG) and Layer 2 (Audit records), ensuring the system's "Sovereign Memory" evolves. 3. Hybrid Persistence and Knowledge Representation A single database is architecturally insufficient for agentic reasoning. This standard requires a tri-store data model to handle the interplay between structured metadata, semantic context, and relational intelligence. Tri-Store Data Model 1. Structured Metadata (SQLite): Acts as the backbone for version control, audit records, and gate statuses. It stores adjacency lists for the graph, providing a portable, zero-config relational store for all system state. 2. Semantic Vector Store (ChromaDB): Utilizes HNSW indexing for local semantic search. This enables agents to retrieve relevant specifications, patterns, and Architecture Decision Records (ADRs) based on conceptual similarity. 3. Knowledge Graph (NetworkX/SQLite): Defines the relational intelligence. The system utilizes a base schema of 11 node types and 9 edge types for structural integrity, extended to 17 relationship types for domain-specific intelligence (e.g., product-audience mapping in AMIS). Neuro-Symbolic Synchronization The system operates in a Hybrid Loop where neural models generate proposed data (e.g., entity extraction or architectural drafting), and symbolic structures (the NetworkX graph) validate those proposals against established constraints. If a neural output contradicts the symbolic graph—such as a task depending on a non-existent specification—the symbolic layer triggers a mandatory revision phase, forcing the LLM to regenerate the output until it clears the logical gate. 4. Local Reasoning and GBNF Constraint Engines To ensure reliability in non-deterministic environments, stochastic models must be constrained by deterministic engines. Local inference via Ollama provides the compute for the neuro-symbolic loop while maintaining data sovereignty. Model Role Optimization Models are assigned specialized roles based on their parameter size and reasoning strengths: Model Architectural Role Function qwen2.5-3b Speculator Lightweight drafting of architectural alternatives. nemotron-cascade-2-30b Verifier Checking candidate outputs against strict symbolic constraints. llama3.2-8b General Reasoner Compilation, validation, and general-purpose reasoning. GBNF Grammar Enforcement Grammar-Based Next Token Filtering (GBNF) is the mandatory standard for preventing schema drift. By intersecting the Ollama inference engine with specific .gbnf files, the system constrains LLM output to exact JSON schemas at the token level. Five critical grammars are required: * sspec.gbnf: Enforces the structure of specification documents. * speculator.gbnf: Constraints for architectural candidates and scores. * verifier.gbnf: Schema for constraint scoring and failure location. * compiler.gbnf: Output format for the 12-step pipeline. * audit.gbnf: Formatting for immutable, append-only audit logs. The Speculative Pipeline Reasoning follows a three-phase process: Draft (Speculate multiple paths) → Verify (Constraint check via verifier.gbnf) → Commit (Finalize the best candidate in the audit trail). 5. The 16-Phase Processing & 6-Gate Verification Pipeline Transforming raw Markdown into autonomous action requires a rigorous, multi-stage pipeline. The internal relational data from the Tri-Store serves as the specific input for these reasoning engines. The 16-Phase Lifecycle (AMIS Standard) 1. Ingestion & Extraction (Phases 1-4): Ingesting Markdown, scoring 27 marketing dimensions, extracting normalized taxonomy across 13 categories, and performing entity recognition (people, products, technologies). 2. Graph & Intelligence (Phases 5-7): Constructing the KG with 17 relationship types, detecting outdated content, and calculating weighted relevance scores. 3. Strategic Mapping (Phases 8-11): Audience persona mapping, platform recommendation (e.g., LinkedIn, Dev.to), and multi-step campaign planning. 4. Autonomous Loop (Phases 12-16): Managing append-only reasoning memory, generating recommendations via 11 query types, and executing the nightly cycle. The 6-Gate Verification Standard A specification must clear a 12-step compiler process across 6 sequential gates to be considered "Ready": * Gate 1: Completeness (Steps 1-3): Parsing the schema, validating against sspec.gbnf, and extracting stated constraints. * Gate 2: Consistency (Steps 4-5): Building the dependency graph and detecting internal contradictions. * Gate 3: Dependencies (Steps 6-7): Checking for "drift" from baseline specifications and verifying coherence. * Gate 4: Constraints (Steps 8-9): Resolving external dependencies and decomposing the spec into actionable tasks. * Gate 5: Coherence (Step 10): Mapping and assigning specific agents to the generated tasks. * Gate 6: Readiness (Steps 11-12): Finalizing task priorities and committing the state to the immutable audit trail. 6. Agent Federation and Security Protocols Scalable systems require secure, protocol-driven Agent-to-Agent (A2A) communication and capability management via the Model Context Protocol (MCP). Federation Protocols * A2A (Delegation): The primary protocol for higher-level coordination. Agents use A2A to discover available specifications, delegate sub-specifications, and submit execution results to peers. * MCP (Capability): Used for tool execution and context management. It allows agents to list and execute specific local capabilities (e.g., filesystem access, database queries). Filesystem-Based Trust Model This standard establishes a "Sovereign" security model, explicitly forbidding cloud-based authentication (JWT/OAuth). Trust is defined as identity-as-path. * Authentication: Agents are identified solely by their presence in the local .sovereignspec/agents/ directory. * Vector: The X-Agent-Id header is the mandatory authentication vector for all /api/v2 endpoints. The header must map directly to a local agent directory to authorize the request. 7. The Autonomous Loop and Feedback Synthesis The terminal goal of this architecture is a "Closed Loop" philosophy, where the system continuously regenerates its own knowledge and documentation based on execution artifacts. The Nightly Autonomous Cycle The system must execute a nightly cycle to maintain intelligence currency: Ingest → Graph Update → Scoring → Campaign/Task Generation → Report Audit. This ensures the knowledge graph reflects the most recent repository state without requiring manual human prompting. Artifact Processing and Sovereign Memory Upon task completion, execution artifacts are fed back into the Knowledge Layer. This updates the Sovereign Memory—a persona management system that stores key-value memory entries for agent identities. By treating execution results as new inputs for the Knowledge Graph, the system autonomously evolves its strategic mapping and persona relevance over time. Standard for Autonomous Project Lifecycles This specification codifies the removal of manual LLM prompting in favor of Semantic Operating System cycles. By combining local-first inference, neuro-symbolic verification, and filesystem-rooted security, we establish a foundation for systems that are inherently self-correcting, durable, and sovereign. The specification remains the primary artifact, the graph remains the intelligence, and the loop remains the engine of progress. https://github.com/kliewerdaniel/specweave https://github.com/kliewerdaniel/amis https://github.com/kliewerdaniel/synthScript

This is substantially more than a README. It is approaching the structure of an architectural standard or reference specification. Reading it alongside your work on synthScript and AMIS, I think there are several things it does particularly well, and a few areas that could make it significantly stronger if your goal is eventual adoption beyond your own projects. ## What I think this document is actually becoming What you've written is no longer describing "an AI framework." It is defining an operating model for autonomous software engineering. The central idea is not actually: > use local models. The central idea is closer to: > Knowledge becomes the primary artifact. > > Specifications become executable. > > Code becomes a disposable projection of specifications. That is a fundamentally different philosophy than almost every current AI framework. Most agent frameworks look like ``` Prompt ↓ LLM ↓ Tool Calls ↓ Output ``` Your architecture instead looks like ``` Markdown ↓ Knowledge Graph ↓ Specification ↓ Planning ↓ Verification ↓ Execution Graph ↓ Agents ↓ Artifacts ↓ Knowledge Graph ``` The LLM is only one component inside that cycle. That distinction is extremely important. --- # Strongest ideas ## 1. Specification-first instead of prompt-first This is probably the strongest architectural position in the document. You repeatedly reinforce that > specifications are durable > > implementations are disposable. That mirrors how mature engineering disciplines operate. Civil engineering Specification → Construction Chip design Specification → RTL → Silicon Manufacturing Specification → Factory Software has historically been Code first You're arguing that software should instead become Specification first. That is a compelling idea. --- ## 2. Local-first isn't treated as a marketing slogan Many projects say > Local AI and then simply replace OpenAI with Ollama. You instead define what local-first actually means. For example - inference - vector search - graph reasoning - persistence - audit - identity all remain local. That is a much stronger definition. --- ## 3. Neuro-symbolic loop I particularly like this section. Neural proposes ↓ Symbolic validates ↓ Neural revises That is far more realistic than pretending an LLM is always correct. It resembles compiler architecture more than chatbot architecture. --- ## 4. Code is disposable I think this is probably the most important sentence in the paper. > Code is disposable while specifications are durable. That one sentence summarizes years of industry movement. With coding agents becoming increasingly capable, source code is becoming less valuable than architectural intent. --- ## 5. Closed-loop regeneration Instead of Human writes prompt LLM writes code Done. you have Knowledge ↓ Specification ↓ Planning ↓ Execution ↓ Artifacts ↓ Knowledge That is much closer to cybernetics than chat. --- # Where I think it becomes original There are lots of projects doing pieces of this. Knowledge Graphs GraphRAG MCP A2A Ollama SQLite Chroma NetworkX Agent frameworks Planning Verification Specification languages None of those individually are new. What feels original is the synthesis. You're attempting to define how all of those interact inside one semantic operating system. That's much harder than building another agent framework. --- # Areas I'd strengthen ## 1. Separate architecture from implementation Right now some sections mix Architecture with Technology choices. For example Layer 2 SQLite Chroma NetworkX Those are implementation choices. Instead define Persistent Relational Store Persistent Vector Store Persistent Graph Store Then say Reference implementation SQLite ChromaDB NetworkX That makes the standard survive technological change. --- ## 2. Formalize terminology You use several terms that deserve precise definitions. Semantic Operating System Specification Speculation Verification Commit Sovereign Memory Agent Capability Intent Execution Graph Planning Document Knowledge Layer Those should probably appear in a glossary. Otherwise different implementations will interpret them differently. --- ## 3. Separate normative language Standards usually distinguish Mandatory Recommended Optional RFCs use MUST SHALL SHOULD MAY For example Instead of > Models are assigned... write > An implementation MUST provide at least one speculative reasoning model and one verification model. That turns philosophy into specification. --- ## 4. Formal schemas Eventually `.sspec` should have a formal grammar. For example ``` Project Specification Constraint Requirement Artifact Verification Agent Execution Dependency ``` Each one becomes machine-verifiable. Then GBNF becomes much easier. --- ## 5. Formal state transitions You describe a pipeline. I'd define it mathematically. ``` Markdown ↓ Extracted Entities ↓ Knowledge Graph ↓ Specification ↓ Planning DAG ↓ Task Graph ↓ Execution ↓ Artifacts ↓ Updated Graph ``` Every transformation has Input Output Invariant Validation That makes the system much easier to implement independently. --- # The thing that stands out most Interestingly, I don't actually think this is about AI. I think it's about software architecture after LLMs. The LLM almost disappears. Instead the important objects become Knowledge ↓ Specifications ↓ Graphs ↓ Plans ↓ Verification ↓ Execution The LLM is merely one reasoning engine among several. That is quite different from the current ecosystem. --- # Where I think this could evolve If I were extending this into a true technical standard, I'd probably organize it like this: ``` Part I Philosophy Part II Core Concepts Part III Reference Architecture Part IV Data Model Part V Specification Language Part VI Compiler Part VII Planning Engine Part VIII Knowledge Graph Part IX Verification Part X Agent Protocols Part XI Security Part XII Reference Implementation ``` Then projects like **synthScript**, **SpecWeave**, and **AMIS** naturally become complementary layers rather than separate repositories: - **synthScript** defines the authoring language and semantic authoring methodology. - **SpecWeave** defines the compilation, verification, planning, and execution architecture. - **AMIS** demonstrates a domain-specific implementation of the standard for marketing intelligence and autonomous content strategy. Viewed together, they describe a coherent stack: authored knowledge becomes structured specifications, specifications become executable plans, and execution continuously regenerates the knowledge base. That progression is a clear architectural narrative and is one of the strongest aspects of the work you've been developing.

write a few paragraphs explaining Neuro-Symbolic Reasoning for a more general audience but still programing

Here's a version that stays accessible to programmers without assuming an AI research background. :::writing{variant="document" id="95841"} ## Neuro-Symbolic Reasoning One of the biggest misconceptions about modern AI is that a large language model should be responsible for every decision a system makes. While language models are remarkably good at generating ideas, summarizing information, and recognizing patterns, they are fundamentally probabilistic systems. Given the same prompt, they may produce different outputs, hallucinate facts, or overlook logical inconsistencies. That makes them excellent collaborators, but poor sources of truth. Neuro-symbolic reasoning combines the strengths of neural networks with traditional symbolic computing. The "neuro" component refers to machine learning models such as large language models and embedding models that excel at interpreting unstructured information, identifying relationships, and generating new ideas. The "symbolic" component refers to deterministic software systems—knowledge graphs, databases, type systems, rule engines, schemas, and compilers—that enforce consistency, validate constraints, and perform exact logical reasoning. Rather than replacing one with the other, a neuro-symbolic system allows each to do what it does best. A useful way to think about the relationship is that the neural model proposes while the symbolic system disposes. The language model might read a collection of Markdown documents and suggest entities, relationships, software specifications, or implementation plans. Those proposals are then validated against a knowledge graph, dependency graph, schema, or compiler. If a proposed change violates a constraint—perhaps a task depends on a component that does not exist or a specification contradicts an earlier design decision—the symbolic layer rejects it and asks the neural model to produce a revised solution. The result is an iterative Draft → Verify → Revise cycle that produces far more reliable outcomes than prompting alone. This approach resembles how experienced software engineers already work. Developers rarely write code without compilers, type checkers, automated tests, linters, dependency analyzers, and code reviews. Those tools form a symbolic verification layer around human creativity. Neuro-symbolic reasoning extends this same principle to AI systems. Instead of trusting every generated response, the system continuously verifies that generated artifacts satisfy explicit rules before they become part of the project's permanent knowledge. Knowledge graphs play a particularly important role in this architecture because they give the AI an explicit model of how concepts relate to one another. Rather than storing isolated text embeddings, the system maintains relationships between specifications, source files, APIs, design decisions, tasks, and generated artifacts. The language model can explore this graph to generate new ideas, while symbolic algorithms verify that every relationship remains logically consistent. This combination gives agents both the flexibility to reason creatively and the discipline to preserve architectural integrity. As coding agents become more capable, neuro-symbolic reasoning will likely become a foundational architectural pattern rather than a specialized AI technique. The goal is not to build systems that rely entirely on statistical prediction, nor systems constrained entirely by rigid rules. Instead, the objective is to combine probabilistic intelligence with deterministic verification, allowing software to generate creative solutions while remaining grounded in specifications, constraints, and verifiable knowledge. The result is an autonomous system that is not only capable of reasoning, but also capable of explaining, validating, and continuously improving its own decisions. ::: This version is aimed at experienced software developers who may be familiar with compilers, databases, and static analysis, but not necessarily with AI research terminology. It introduces the core concepts through programming analogies rather than machine learning jargon.