Empowering AI Agents: A Deep Dive into Selectable Knowledge Injection with Axiom

The dream of truly intelligent AI agents isn't just about sophisticated models; it's about giving them the right context at the right time. Our latest development sprint was all about making that a reality by integrating "Axiom" – our internal knowledge base – directly into our core features: Workflows, AutoFix, and Refactor.

This wasn't just about dumping all available information into the prompt. It was about control, relevance, and precision. We wanted our users to dictate exactly which pieces of external knowledge their AI agents should consider. And after a focused development session, I'm thrilled to report that it's fully implemented, type-checked, and ready to empower our users.

The Core Idea: Axiom Injection

Imagine an AI agent trying to refactor a complex codebase or generate a new feature. While it has access to the codebase itself and its own conversational memory, what if it also needed to understand specific design patterns documented in an internal wiki, or comply with a particular set of coding standards? That's where Axiom comes in.

Axiom represents a structured collection of documents – internal specifications, architecture guides, best practices, or even just detailed notes. By injecting relevant Axiom content, we can significantly reduce AI "hallucinations" and ensure its outputs are aligned with our project's specific context and goals. The challenge was making this injection intelligent and user-configurable.

Designing for Flexibility: Four Modes of Context

To provide maximum utility, we designed Axiom injection with four distinct modes, allowing users to fine-tune the context provided to the AI:

1. Off (None): No Axiom content is injected. Simple, clean, and useful when external knowledge isn't required.
2. All: Every chunk from all available Axiom documents within the current project scope is injected. A broad-stroke approach for when comprehensive knowledge is needed.
3. Category: Users select one or more categories (e.g., "Frontend Architecture," "Security Guidelines"). Only documents belonging to these categories are considered for injection. This provides a focused, high-level filter.
4. Selected: The most granular control. Users can search and pick specific Axiom documents by ID. This is perfect for pinpointing exact specifications or reference materials.

This level of granularity means our AI agents can be as broad or as laser-focused as the task demands, ensuring optimal performance and relevance.

Under the Hood: The Technical Journey

Implementing this required touching almost every layer of our stack, from the database schema to the UI.

1. Evolving the Data Model

First, we needed to store the user's Axiom configuration. This meant adding new fields to our Workflow model in prisma/schema.prisma:

model Workflow {
  // ... other fields
  axiomMode           String?
  axiomCategories     String[]
  axiomDocumentIds    String[]
  // ...
}

These fields (axiomMode, axiomCategories, axiomDocumentIds) would hold the user's selection for how Axiom content should be injected into a specific workflow. Similar configurations were designed for AutoFix and Refactor runs, stored as JSON blobs within their respective run configurations.

2. The AxiomPicker Component: A User's Control Panel

On the frontend, the core of this feature is the AxiomPicker component (src/components/workflow/axiom-picker.tsx). This component encapsulates the entire user experience for selecting Axiom injection modes. It features:

• Mode Selection: Radio buttons or dropdowns for "Off," "All," "Category," and "Selected."
• Category Chips: For "Category" mode, users can easily select and deselect categories.
• Document Search & Selection: For "Selected" mode, a powerful search interface (similar to our wisdom/memory picker) allows users to find and choose specific documents, complete with "authority badges" for quick identification.
• Collapsible Section: Integrated into the UI with a distinct "Shield" icon, indicating its role in providing protective, authoritative knowledge.

3. The RAG Engine's New Brain: Loading Axiom Content

The real magic happens in our RAG (Retrieval-Augmented Generation) service. We updated src/server/services/rag/load-axiom-content.ts to understand our new AxiomConfig type. This service is now responsible for:

• "Selected" Mode: Loading all chunks from a precise list of document IDs.
• "Category" Mode: Filtering documents by selected categories, then loading their chunks.
• "All" Mode: Our existing backward-compatible logic to load all relevant Axiom chunks.

This loadAxiomContent() function became a critical piece, acting as the gateway for structured knowledge.

4. Seamless Integration into the AI Pipeline

The Axiom content isn't just loaded; it needs to be integrated into the AI's prompt context. We modified src/server/services/pipeline-context.ts to include Axiom as a new source of information. It now sits strategically in the AI's processing pipeline, typically between conversational memory and broader discussions, ensuring it's available when the AI generates its response or action.

// Conceptual snippet from pipeline-context.ts
async function loadPipelineContext(options: PipelineOptions): Promise<PipelineContext> {
  // ... load memory, code, discussions ...

  let axiomContent = '';
  if (options.axiomConfig) {
    axiomContent = await loadAxiomContent(options.projectId, options.axiomConfig);
  }

  return {
    // ...
    axiom: axiomContent, // Available as {{axiom}} in prompt templates
    // ...
  };
}

5. Backend & Frontend Integration Across Features

Finally, we wired everything together:

• Workflows: src/server/services/workflow-engine.ts and src/server/trpc/routers/workflows.ts were updated to accept and pass the axiomMode, axiomCategories, and axiomDocumentIds directly from the Workflow model to the loadAxiomContent() function. The AxiomPicker was added to src/app/(dashboard)/dashboard/workflows/new/page.tsx.
• AutoFix & Refactor: These features followed a similar pattern. Their start mutations (src/server/trpc/routers/auto-fix.ts, src/server/trpc/routers/refactor.ts) now accept a comprehensive axiomConfig object, which is stored in the run's configuration JSON. API event routes (src/app/api/v1/events/auto-fix/[id]/route.ts, src/app/api/v1/events/refactor/[id]/route.ts) and their respective pipelines (src/server/services/auto-fix/pipeline.ts, src/server/services/refactor/pipeline.ts) were updated to pass this axiomConfig through to loadPipelineContext(). The AxiomPicker was integrated into their start dialogs (src/app/(dashboard)/dashboard/auto-fix/page.tsx, src/app/(dashboard)/dashboard/refactor/page.tsx).

After all these changes, a quick npm run db:push to apply the new schema fields and a clean typecheck confirmed everything was in order.

A Bump in the Road: Lessons Learned from Prisma

No significant feature ships without a small hiccup or two. For this session, it was a classic one related to schema changes and our ORM, Prisma.

The Problem: I instinctively ran npm run typecheck right after modifying prisma/schema.prisma but before running npm run db:push. The Result: Typecheck failed spectacularly. The TypeScript compiler, through the Prisma client, didn't know about the newly added axiomMode, axiomCategories, and axiomDocumentIds fields on the Workflow model. The Fix: A quick npm run db:push (which automatically regenerates the Prisma client based on the updated schema) immediately resolved the issue, and typecheck passed cleanly thereafter.

Lesson Learned: When making schema changes with Prisma, always remember to run db:push (or migrate dev) before expecting your TypeScript codebase to correctly reflect those changes. The Prisma client generation step is crucial for type safety. It's a fundamental step I sometimes forget in the heat of development!

What's Next?

With the core implementation complete, our immediate next steps involve thorough end-to-end testing:

• Verify Axiom injection in Workflows: Upload documents, create a workflow with "category" mode, and confirm {{axiom}} content appears as expected.
• Test AutoFix/Refactor: Start a scan with "all" mode and ensure project context correctly includes Axiom content.
• Consider extending AxiomPicker to other features, like code analysis, if the need arises.

This feature dramatically enhances the intelligence and reliability of our AI agents by giving users unprecedented control over the knowledge they consume. It's a significant step towards building truly context-aware and powerful development tools.

{
  "thingsDone": [
    "Implemented Axiom document injection for Workflows, AutoFix, and Refactor features.",
    "Designed and integrated 4 modes for Axiom injection: none, all, category, selected.",
    "Updated Prisma schema to include new fields for Axiom configuration on the Workflow model.",
    "Developed a reusable AxiomPicker React component with search, category chips, and authority badges.",
    "Enhanced RAG service (load-axiom-content.ts) to support all Axiom injection modes.",
    "Integrated Axiom content loading into the main AI pipeline context (pipeline-context.ts).",
    "Updated backend services (workflow-engine, tRPC routers) to pass Axiom configuration.",
    "Modified API event routes and feature pipelines (AutoFix, Refactor) to utilize Axiom config.",
    "Integrated AxiomPicker into relevant frontend pages (Workflows, AutoFix, Refactor new/start forms).",
    "Applied database schema changes with `npm run db:push`."
  ],
  "pains": [
    "Encountered type-checking failures due to Prisma client not being regenerated after schema changes, before `db:push`."
  ],
  "successes": [
    "Achieved full implementation of Axiom injection with flexible configuration.",
    "Successfully integrated Axiom into multiple core features (Workflows, AutoFix, Refactor).",
    "Developed a robust and user-friendly AxiomPicker component.",
    "Ensured backward compatibility for existing features.",
    "Resolved schema migration/type-checking issue efficiently with correct Prisma workflow."
  ],
  "techStack": [
    "TypeScript",
    "React",
    "Next.js",
    "Prisma",
    "PostgreSQL",
    "tRPC",
    "RAG (Retrieval-Augmented Generation)",
    "AI Agents"
  ]
}