.env.ai-km

interface KnowledgeDocument {
  id: string;
  source: string;
  title: string;
  content: string;
  metadata: Record<string, string | string[]>;
  updatedAt: Date;
}

async function normalizeSource(raw: string, sourceType: 'markdown' | 'html' | 'text'): Promise<KnowledgeDocument> {
  // Production: Use unified/markdown-it or cheerio for HTML
  const cleaned = raw
    .replace(/<script[\s\S]*?>[\s\S]*?<\/script>/gi, '')
    .replace(/<style[\s\S]*?>[\s\S]*?<\/style>/gi, '')
    .trim();

  return {
    id: crypto.randomUUID(),
    source: sourceType,
    title: '', // Extracted via heuristic or LLM
    content: cleaned,
    metadata: { category: ['engineering'], version: ['latest'] },
    updatedAt: new Date()
  };
}

interface Chunk {
  id: string;
  content: string;
  metadata: Record<string, string | string[]>;
  parentDocId: string;
}

function semanticChunk(doc: KnowledgeDocument, maxTokens = 350, overlap = 50): Chunk[] {
  const chunks: Chunk[] = [];
  const paragraphs = doc.content.split(/\n\s*\n/).filter(p => p.trim().length > 0);
  
  let currentChunk = '';
  let currentTokens = 0;

  for (const para of paragraphs) {
    const paraTokens = estimateTokens(para);
    
    if (currentTokens + paraTokens > maxTokens && currentChunk) {
      chunks.push({
        id: crypto.randomUUID(),
        content: currentChunk.trim(),
        metadata: { ...doc.metadata, chunkIndex: String(chunks.length) },
        parentDocId: doc.id
      });
      
      // Overlap preserves context across boundaries
      const overlapText = currentChunk.split(' ').slice(-overlap).join(' ');
      currentChunk = overlapText + '\n' + para;
      currentTokens = estimateTokens(currentChunk);
    } else {
      currentChunk += (currentChunk ? '\n' : '') + para;
      currentTokens += paraTokens;
    }
  }

  if (currentChunk) {
    chunks.push({
      id: crypto.randomUUID(),
      content: currentChunk.trim(),
      metadata: { ...doc.metadata, chunkIndex: String(chunks.length) },
      parentDocId: doc.id
    });
  }

  return chunks;
}

function estimateTokens(text: string): number {
  // Approximation: 1 token ≈ 4 chars for English. Use tiktoken in production.
  return Math.ceil(text.length / 4);
}

import { createClient } from '@lancedb/lancedb';

async function upsertChunks(chunks: Chunk[], embeddingClient: any) {
  const db = await createClient('./ai-km-store');
  const table = await db.openTable('knowledge_chunks');

  const records = await Promise.all(
    chunks.map(async chunk => {
      const embedding = await embeddingClient.embed(chunk.content);
      return {
        chunk_id: chunk.id,
        content: chunk.content,
  

  parent_doc_id: chunk.parentDocId,
    metadata: JSON.stringify(chunk.metadata),
    vector: embedding
  };
})

);

await table.add(records); await table.createIndex({ type: 'ivf_pq', column: 'vector', num_partitions: 16, num_sub_vectors: 8 }); }

### Step 4: Hybrid Retrieval & RAG Pipeline
Vector search alone misses exact matches (error codes, API endpoints). Combine dense retrieval with BM25 lexical search. Apply metadata filters for access control and routing.

```typescript
interface RetrievalResult {
  chunkId: string;
  score: number;
  content: string;
  metadata: Record<string, string | string[]>;
}

async function hybridSearch(query: string, filters: Record<string, string>, limit = 5): Promise<RetrievalResult[]> {
  // 1. Vector similarity search
  const queryEmbedding = await embeddingClient.embed(query);
  const vectorResults = await table
    .search(queryEmbedding)
    .limit(limit)
    .where(buildFilterExpression(filters))
    .toArray();

  // 2. BM25 lexical search (via PostgreSQL tsvector or Elasticsearch)
  const lexicalResults = await lexicalSearch(query, filters, limit);

  // 3. Reciprocal Rank Fusion (RRF)
  const fused = reciprocalRankFusion(vectorResults, lexicalResults);
  
  return fused.slice(0, limit).map(r => ({
    chunkId: r.chunk_id,
    score: r.score,
    content: r.content,
    metadata: JSON.parse(r.metadata)
  }));
}

function reciprocalRankFusion(vector: any[], lexical: any[], k = 60): any[] {
  const scoreMap = new Map<string, number>();
  
  for (const item of vector) {
    scoreMap.set(item.chunk_id, (scoreMap.get(item.chunk_id) || 0) + 1 / (k + item._distance));
  }
  for (const item of lexical) {
    scoreMap.set(item.chunk_id, (scoreMap.get(item.chunk_id) || 0) + 1 / (k + item._rank));
  }

  return Array.from(scoreMap.entries())
    .map(([chunkId, score]) => ({ chunkId, score }))
    .sort((a, b) => b.score - a.score);
}

Step 5: Synthesis & Grounding

Never allow the LLM to generate without explicit grounding constraints. Use a strict prompt template that forces citation and refusal when context is insufficient.

async function synthesizeAnswer(query: string, context: RetrievalResult[]): Promise<string> {
  const prompt = `
    You are a technical knowledge assistant. Answer using ONLY the provided context.
    If the context does not contain sufficient information, respond with: "INSUFFICIENT_CONTEXT".
    Cite chunk IDs using [chunk_id] notation.
    
    Context:
    ${context.map(c => `[${c.chunkId}] ${c.content}`).join('\n\n')}
    
    Query: ${query}
  `;

  const response = await llmClient.complete(prompt, {
    temperature: 0.1,
    max_tokens: 800,
    stop_sequences: ['</answer>']
  });

  return response.text;
}

Architecture Decisions & Rationale

• Hybrid Retrieval over Pure Vector: Vector embeddings excel at semantic similarity but degrade on exact technical identifiers. BM25 compensates for this gap. RRF fusion balances both without complex weighting.
• Metadata-First Filtering: Access control, product versioning, and environment routing must happen at retrieval time, not post-processing. Storing metadata alongside vectors enables zero-latency filtering.
• Deterministic Grounding: LLMs are pattern generators, not databases. The synthesis step must enforce strict context boundaries. Temperature is capped at 0.1 to minimize creative deviation.
• Incremental Ingestion: Full re-embedding is cost-prohibitive. Track document hashes and chunk fingerprints. Only re-embed modified segments. Use tombstone markers for deleted content.

Pitfall Guide

1. Uniform Chunking Without Context Boundaries Splitting documents at fixed character counts breaks code examples, API references, and logical sections. Semantic chunking that respects headings, paragraphs, and code fences preserves retrieval relevance. Always validate chunk boundaries against technical documentation structure.

2. Ignoring Metadata and Access Controls Embedding everything into a single vector space creates security leaks and noise. Product version, team ownership, and environment tags must be stored as queryable metadata. Filtering at retrieval time prevents cross-tenant data exposure and reduces irrelevant context injection.

3. Treating LLMs as Databases Developers frequently prompt LLMs to "remember" internal processes without retrieval. This guarantees hallucination. The LLM should only synthesize what the retrieval layer returns. Grounding constraints are non-negotiable in production.

4. Static Knowledge Bases AI-KM systems decay rapidly. Documentation updates, deprecations, and incident post-mortems require continuous ingestion. Implement a webhook-driven pipeline that triggers re-chunking and re-embedding on source changes. Schedule weekly integrity scans.

5. Over-Engineering the Retrieval Layer Adding cross-encoders, query expansion, and multi-hop reasoning before establishing baseline hybrid search increases latency without proportional gains. Start with vector + BM25 + RRF. Add complexity only when evaluation metrics plateau.

6. Neglecting Evaluation Frameworks Without precision@k, recall, and faithfulness scoring, teams cannot measure degradation. Implement RAGAS or custom evaluation pipelines that test against golden queries. Track hallucination rates and context relevance weekly.

Best Practice: Maintain a feedback loop. Log user corrections, downvotes, and follow-up queries. Use this signal to reweight retrieval parameters, adjust chunk overlap, and flag outdated documents for review.

Production Bundle

Action Checklist

• Define knowledge sources and normalization schema: Map all repositories, wikis, and ticket systems to a unified document interface.
• Implement semantic chunking with overlap: Validate boundaries against code fences and section headers. Test token distribution.
• Deploy hybrid retrieval pipeline: Configure vector search, BM25 index, and RRF fusion. Add metadata filtering for access control.
• Enforce grounding constraints in synthesis: Use strict prompts, low temperature, and citation requirements. Implement INSUFFICIENT_CONTEXT fallback.
• Build incremental ingestion workflow: Track document hashes, trigger selective re-embedding, and maintain tombstone markers for deletions.
• Establish evaluation metrics: Deploy precision@5, hallucination rate, and latency monitoring. Schedule weekly benchmark runs.
• Implement feedback routing: Capture user corrections and route them to documentation owners. Close the loop with automated re-ingestion.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup MVP (<50k docs)	LanceDB + OpenAI embeddings + RRF	Low operational overhead, fast deployment, sufficient accuracy	$120-180/mo (embeddings + infra)
Enterprise Compliance (SOC2, RBAC)	pgvector + Elasticsearch hybrid + metadata ACLs	Strict access control, audit trails, self-hosted vector storage	$450-650/mo (managed DB + compute)
High-Throughput Internal Tools (>500k docs)	Qdrant + custom BM25 + cross-encoder reranker	Scales to millions of vectors, sub-100ms latency, handles complex routing	$800-1,200/mo (cluster + GPU reranking)

Configuration Template

# .env.ai-km
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIM=1536
LLM_MODEL=gpt-4o-mini
LLM_TEMP=0.1
MAX_CHUNK_TOKENS=350
CHUNK_OVERLAP=50
VECTOR_DB_PROVIDER=lancedb
VECTOR_DB_PATH=./ai-km-store
BM25_ENDPOINT=http://localhost:9200
METADATA_FILTER_ENABLED=true
EVALUATION_INTERVAL_HOURS=168

// config/ai-km.config.ts
export const AI_KM_CONFIG = {
  embedding: {
    model: process.env.EMBEDDING_MODEL || 'text-embedding-3-small',
    dimensions: parseInt(process.env.EMBEDDING_DIM || '1536'),
    batchSize: 100,
    retryAttempts: 3
  },
  chunking: {
    maxTokens: parseInt(process.env.MAX_CHUNK_TOKENS || '350'),
    overlap: parseInt(process.env.CHUNK_OVERLAP || '50'),
    strategy: 'semantic'
  },
  retrieval: {
    topK: 5,
    rrfK: 60,
    minScore: 0.65,
    hybrid: {
      vectorWeight: 0.7,
      lexicalWeight: 0.3
    }
  },
  synthesis: {
    model: process.env.LLM_MODEL || 'gpt-4o-mini',
    temperature: parseFloat(process.env.LLM_TEMP || '0.1'),
    maxTokens: 800,
    grounding: 'strict',
    fallback: 'INSUFFICIENT_CONTEXT'
  },
  evaluation: {
    enabled: true,
    intervalHours: parseInt(process.env.EVALUATION_INTERVAL_HOURS || '168'),
    metrics: ['precision@5', 'hallucination_rate', 'latency_p95']
  }
};

Quick Start Guide

1. Initialize the repository: Clone the template, run npm install, and copy .env.ai-km to .env. Set your embedding and LLM API keys.
2. Start local dependencies: Run docker compose up -d to launch LanceDB and a lightweight BM25 indexer. Verify connectivity with curl http://localhost:9200.
3. Ingest sample documentation: Execute npm run ingest -- --source ./docs --recursive. The pipeline will normalize, chunk, embed, and index 50 sample files in ~90 seconds.
4. Query the system: Run npm run query "How do I configure rate limiting for the auth service?". The system returns a grounded answer with chunk citations and a relevance score.
5. Validate metrics: Execute npm run eval -- --golden ./tests/golden-queries.json. Review precision@5 and hallucination rate in the console output. Adjust chunk overlap or RRF weights if precision falls below 0.80.

AI-powered knowledge management is not a chatbot feature. It is a retrieval engineering discipline. Success depends on deterministic chunking, hybrid search orchestration, strict grounding, and continuous evaluation. Deploy the pipeline, measure relentlessly, and iterate on retrieval quality. The model will follow.