feat(sdk): load knowledge files from user home directory

Add support for loading knowledge files (~/.knowledge.md, ~/.AGENTS.md,
or ~/.CLAUDE.md) from the user's home directory with priority fallback.

Changes:
- Add shared constants in common/src/constants/knowledge.ts:
  - KNOWLEDGE_FILE_NAMES array with priority order
  - PRIMARY_KNOWLEDGE_FILE_NAME for explicit primary file reference
  - isKnowledgeFile() with stricter matching (exact names or *.knowledge.md)
- Add loadUserKnowledgeFiles() to load from home directory
- Update initialSessionState to populate userKnowledgeFiles
- Accept userKnowledgeFiles param that merges with home dir files
- Update prompts to mention AGENTS.md support
- Consolidate duplicate constants across CLI, SDK, and evals
- Add comprehensive tests for all new functionality

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>

Author: brandonkachen

cli/src/commands/init.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, writeFileSync } from 'fs'
 import path from 'path'
 
 import { AnalyticsEvent } from '@codebuff/common/constants/analytics-events'
+import { PRIMARY_KNOWLEDGE_FILE_NAME } from '@codebuff/common/constants/knowledge'
 
 // @ts-expect-error - Bun text import attribute not supported by TypeScript
 import agentDefinitionSource from '../../../common/src/templates/initial-agents-dir/types/agent-definition' with { type: 'text' }
@@ -16,8 +17,6 @@ import { getSystemMessage } from '../utils/message-history'
 
 import type { PostUserMessageFn } from '../types/contracts/send-message'
 
-const KNOWLEDGE_FILE_NAME = 'knowledge.md'
-
 const INITIAL_KNOWLEDGE_FILE = `# Project knowledge
 
 This file gives Codebuff context about your project: goals, commands, conventions, and gotchas.
@@ -56,19 +55,19 @@ export function handleInitializationFlowLocally(): {
   postUserMessage: PostUserMessageFn
 } {
   const projectRoot = getProjectRoot()
-  const knowledgePath = path.join(projectRoot, KNOWLEDGE_FILE_NAME)
+  const knowledgePath = path.join(projectRoot, PRIMARY_KNOWLEDGE_FILE_NAME)
   const messages: string[] = []
 
   if (existsSync(knowledgePath)) {
-    messages.push(`📋 \`${KNOWLEDGE_FILE_NAME}\` already exists.`)
+    messages.push(`📋 \`${PRIMARY_KNOWLEDGE_FILE_NAME}\` already exists.`)
   } else {
     writeFileSync(knowledgePath, INITIAL_KNOWLEDGE_FILE)
-    messages.push(`✅ Created \`${KNOWLEDGE_FILE_NAME}\``)
+    messages.push(`✅ Created \`${PRIMARY_KNOWLEDGE_FILE_NAME}\``)
 
     // Track knowledge file creation
     trackEvent(AnalyticsEvent.KNOWLEDGE_FILE_UPDATED, {
       action: 'created',
-      fileName: KNOWLEDGE_FILE_NAME,
+      fileName: PRIMARY_KNOWLEDGE_FILE_NAME,
       fileSizeBytes: Buffer.byteLength(INITIAL_KNOWLEDGE_FILE, 'utf8'),
     })
   }

common/src/constants/knowledge.ts

@@ -0,0 +1,46 @@
+import path from 'path'
+
+/**
+ * The primary/default knowledge file name.
+ * Used when creating new knowledge files.
+ */
+export const PRIMARY_KNOWLEDGE_FILE_NAME = 'knowledge.md'
+
+/**
+ * Knowledge file names in priority order (highest priority first).
+ * Used for both project knowledge files and home directory user knowledge files.
+ */
+export const KNOWLEDGE_FILE_NAMES = [
+  PRIMARY_KNOWLEDGE_FILE_NAME,
+  'AGENTS.md',
+  'CLAUDE.md',
+] as const
+
+/**
+ * Pre-computed lowercase knowledge file names for efficient matching.
+ */
+export const KNOWLEDGE_FILE_NAMES_LOWERCASE = KNOWLEDGE_FILE_NAMES.map((name) =>
+  name.toLowerCase(),
+)
+
+/**
+ * Checks if a file path is a knowledge file.
+ * Matches:
+ * - Exact file names: knowledge.md, AGENTS.md, CLAUDE.md (case-insensitive)
+ * - Pattern: *.knowledge.md (e.g., authentication.knowledge.md)
+ */
+export function isKnowledgeFile(filePath: string): boolean {
+  const fileName = path.basename(filePath).toLowerCase()
+
+  // Check for exact matches with standard knowledge file names
+  if (KNOWLEDGE_FILE_NAMES_LOWERCASE.includes(fileName)) {
+    return true
+  }
+
+  // Check for *.knowledge.md pattern (e.g., authentication.knowledge.md)
+  if (fileName.endsWith('.knowledge.md')) {
+    return true
+  }
+
+  return false
+}

evals/scaffolding.ts

@@ -3,6 +3,7 @@ import fs from 'fs'
 import path from 'path'
 
 import { getFileTokenScores } from '@codebuff/code-map/parse'
+import { isKnowledgeFile } from '@codebuff/common/constants/knowledge'
 import { getSystemInfo } from '@codebuff/common/util/system-info'
 
 import {
@@ -36,9 +37,7 @@ export async function getProjectFileContext(
     fs: fs.promises,
   })
   const allFilePaths = getAllFilePaths(fileTree)
-  const knowledgeFilePaths = allFilePaths.filter((filePath) =>
-    filePath.endsWith('knowledge.md'),
-  )
+  const knowledgeFilePaths = allFilePaths.filter(isKnowledgeFile)
   const knowledgeFiles: Record<string, string> = {}
   for (const filePath of knowledgeFilePaths) {
     const content = readMockFile(projectPath, filePath)

packages/agent-runtime/src/system-prompt/prompts.ts

@@ -14,13 +14,13 @@ import type { ProjectFileContext } from '@codebuff/common/util/file'
 export const knowledgeFilesPrompt = `
 # Knowledge files
 
-Knowledge files are your guide to the project. Knowledge files (files ending in "knowledge.md" or "CLAUDE.md") within a directory capture knowledge about that portion of the codebase. They are another way to take notes in this "Memento"-style environment.
+Knowledge files are your guide to the project. Knowledge files (files ending in "knowledge.md", "AGENTS.md", or "CLAUDE.md") within a directory capture knowledge about that portion of the codebase. They are another way to take notes in this "Memento"-style environment.
 
 Knowledge files were created by previous engineers working on the codebase, and they were given these same instructions. They contain key concepts or helpful tips that are not obvious from the code. e.g., let's say I want to use a package manager aside from the default. That is hard to find in the codebase and would therefore be an appropriate piece of information to add to a knowledge file.
 
 Each knowledge file should develop over time into a concise but rich repository of knowledge about the files within the directory, subdirectories, or the specific file it's associated with.
 
-There is a special class of user knowledge files that are stored in the user's home directory, e.g. \`~/.knowledge.md\`. These files are available to be read, but you cannot edit them because they are outside of the project directory. Do not try to edit them.
+There is a special class of user knowledge files that are stored in the user's home directory, e.g. \`~/.knowledge.md\`, \`~/.AGENTS.md\`, or \`~/.CLAUDE.md\`. These files are available to be read, but you cannot edit them because they are outside of the project directory. Do not try to edit them.
 
 When should you update a knowledge file?
 - If the user gives broad advice to "always do x", that is a good candidate for updating a knowledge file with a concise rule to follow or bit of advice so you won't make the mistake again.

packages/agent-runtime/src/templates/strings.ts

@@ -1,3 +1,4 @@
+import { KNOWLEDGE_FILE_NAMES_LOWERCASE } from '@codebuff/common/constants/knowledge'
 import { escapeString } from '@codebuff/common/util/string'
 import { z } from 'zod/v4'
 
@@ -117,9 +118,11 @@ export async function formatPrompt(
       Object.entries({
         ...Object.fromEntries(
           Object.entries(fileContext.knowledgeFiles)
-            .filter(([path]) =>
-              ['knowledge.md', 'CLAUDE.md'].includes(path),
-            )
+            .filter(([filePath]) => {
+              const lowerPath = filePath.toLowerCase()
+              // Root-level knowledge files only (knowledge.md, AGENTS.md, CLAUDE.md)
+              return KNOWLEDGE_FILE_NAMES_LOWERCASE.includes(lowerPath)
+            })
             .map(([path, content]) => [path, content.trim()]),
         ),
         ...fileContext.userKnowledgeFiles,

sdk/README.md

@@ -136,6 +136,24 @@ main()
 
 ## API Reference
 
+### Knowledge Files
+
+Knowledge files provide project context to the agent. The SDK auto-discovers:
+
+- **Project files**: `knowledge.md`, `AGENTS.md`, or `CLAUDE.md` in each directory (priority order)
+- **User files**: `~/.knowledge.md`, `~/.AGENTS.md`, or `~/.CLAUDE.md` (case-insensitive)
+
+Override with `knowledgeFiles` (replaces project files) or `userKnowledgeFiles` (merges with home directory files):
+
+```typescript
+await client.run({
+  agent: 'codebuff/base@0.0.16',
+  prompt: 'Help me refactor',
+  knowledgeFiles: { 'knowledge.md': '# Guidelines\n- Use TypeScript' },
+  userKnowledgeFiles: { '~/.knowledge.md': '# Preferences\n- Be concise' },
+})
+```
+
 ### File Filtering
 
 The `fileFilter` option controls which files the agent can read:

sdk/src/__tests__/knowledge-file-selection.test.ts

@@ -1,6 +1,132 @@
 import { describe, expect, test } from 'bun:test'
 
-import { selectKnowledgeFilePaths } from '../run-state'
+import {
+  KNOWLEDGE_FILE_NAMES,
+  isKnowledgeFile,
+  selectHighestPriorityKnowledgeFile,
+  selectKnowledgeFilePaths,
+} from '../run-state'
+
+describe('KNOWLEDGE_FILE_NAMES', () => {
+  test('contains expected file names in priority order', () => {
+    expect(KNOWLEDGE_FILE_NAMES).toEqual([
+      'knowledge.md',
+      'AGENTS.md',
+      'CLAUDE.md',
+    ])
+  })
+})
+
+describe('isKnowledgeFile', () => {
+  test('returns true for knowledge.md', () => {
+    expect(isKnowledgeFile('knowledge.md')).toBe(true)
+    expect(isKnowledgeFile('src/knowledge.md')).toBe(true)
+    expect(isKnowledgeFile('KNOWLEDGE.MD')).toBe(true)
+  })
+
+  test('returns true for AGENTS.md', () => {
+    expect(isKnowledgeFile('AGENTS.md')).toBe(true)
+    expect(isKnowledgeFile('src/agents.md')).toBe(true)
+    expect(isKnowledgeFile('Agents.MD')).toBe(true)
+  })
+
+  test('returns true for CLAUDE.md', () => {
+    expect(isKnowledgeFile('CLAUDE.md')).toBe(true)
+    expect(isKnowledgeFile('src/claude.md')).toBe(true)
+    expect(isKnowledgeFile('Claude.MD')).toBe(true)
+  })
+
+  test('returns true for *.knowledge.md pattern', () => {
+    expect(isKnowledgeFile('authentication.knowledge.md')).toBe(true)
+    expect(isKnowledgeFile('src/api.knowledge.md')).toBe(true)
+    expect(isKnowledgeFile('docs/AUTH.KNOWLEDGE.MD')).toBe(true)
+    expect(isKnowledgeFile('foo.bar.knowledge.md')).toBe(true)
+  })
+
+  test('returns false for non-knowledge files', () => {
+    expect(isKnowledgeFile('README.md')).toBe(false)
+    expect(isKnowledgeFile('src/utils.ts')).toBe(false)
+    expect(isKnowledgeFile('knowledge.txt')).toBe(false)
+    expect(isKnowledgeFile('agents.txt')).toBe(false)
+  })
+
+  test('returns false for files with knowledge in name but no dot separator', () => {
+    // These should NOT match - stricter matching requires exact filename or .knowledge.md suffix
+    expect(isKnowledgeFile('myknowledge.md')).toBe(false)
+    expect(isKnowledgeFile('src/authknowledge.md')).toBe(false)
+    expect(isKnowledgeFile('preknowledge.md')).toBe(false)
+  })
+
+  test('returns false for similar but non-matching patterns', () => {
+    // .agents.md and .claude.md patterns should NOT match
+    expect(isKnowledgeFile('auth.agents.md')).toBe(false)
+    expect(isKnowledgeFile('auth.claude.md')).toBe(false)
+    expect(isKnowledgeFile('foo.AGENTS.md')).toBe(false)
+    expect(isKnowledgeFile('foo.CLAUDE.md')).toBe(false)
+  })
+})
+
+describe('selectHighestPriorityKnowledgeFile', () => {
+  test('returns undefined for empty array', () => {
+    expect(selectHighestPriorityKnowledgeFile([])).toBeUndefined()
+  })
+
+  test('returns undefined when no knowledge files present', () => {
+    expect(
+      selectHighestPriorityKnowledgeFile(['README.md', 'src/utils.ts']),
+    ).toBeUndefined()
+  })
+
+  test('returns the only knowledge file', () => {
+    expect(selectHighestPriorityKnowledgeFile(['AGENTS.md'])).toBe('AGENTS.md')
+  })
+
+  test('prefers knowledge.md over AGENTS.md', () => {
+    expect(
+      selectHighestPriorityKnowledgeFile(['AGENTS.md', 'knowledge.md']),
+    ).toBe('knowledge.md')
+  })
+
+  test('prefers knowledge.md over CLAUDE.md', () => {
+    expect(
+      selectHighestPriorityKnowledgeFile(['CLAUDE.md', 'knowledge.md']),
+    ).toBe('knowledge.md')
+  })
+
+  test('prefers AGENTS.md over CLAUDE.md', () => {
+    expect(selectHighestPriorityKnowledgeFile(['CLAUDE.md', 'AGENTS.md'])).toBe(
+      'AGENTS.md',
+    )
+  })
+
+  test('prefers knowledge.md when all three exist', () => {
+    expect(
+      selectHighestPriorityKnowledgeFile([
+        'CLAUDE.md',
+        'AGENTS.md',
+        'knowledge.md',
+      ]),
+    ).toBe('knowledge.md')
+  })
+
+  test('handles case-insensitive matching', () => {
+    expect(selectHighestPriorityKnowledgeFile(['KNOWLEDGE.MD'])).toBe(
+      'KNOWLEDGE.MD',
+    )
+    expect(selectHighestPriorityKnowledgeFile(['agents.md'])).toBe('agents.md')
+    expect(selectHighestPriorityKnowledgeFile(['Claude.md'])).toBe('Claude.md')
+  })
+
+  test('filters out non-knowledge files before selecting', () => {
+    expect(
+      selectHighestPriorityKnowledgeFile([
+        'README.md',
+        'AGENTS.md',
+        'utils.ts',
+      ]),
+    ).toBe('AGENTS.md')
+  })
+})
 
 describe('selectKnowledgeFilePaths', () => {
   test('selects knowledge.md when it exists alone', () => {