agent/knowledge/ is an eve-knowledge convention, not a native Eve slot. The package indexes those files explicitly and exposes them through a generated search_knowledge Eve tool.

Quickstart

Requires Node.js 24 or newer, matching Eve's current runtime requirement.

npm install eve-knowledge
npx eve-knowledge init
npx eve-knowledge index
npx eve-knowledge doctor
npx eve-knowledge search "refund policy"

A tiny support-agent demo in examples/basic-eve-agent shows the generated search flow. Run it from a clone with npm run demo:support.

init creates:

agent/
  knowledge/
    README.md
    .eveknowledgeignore
  tools/
    search_knowledge.ts
  skills/
    answer-with-citations.md
eve-knowledge.config.json

Mental Model

• instructions.md tells the agent how to behave.
• tools/ exposes typed runtime actions.
• skills/ are load-on-demand procedures and playbooks.
• connections/ connect external MCP or OpenAPI services.
• agent/knowledge/ is reference material indexed by eve-knowledge.

When To Use What

| Need | Use | Why | | --- | --- | --- | | Permanent behavior and personality | agent/instructions.md | Always-on guidance for the agent. | | A typed runtime action | agent/tools/ | Tools execute code and can access runtime services. | | A procedure the model should load on demand | agent/skills/ | Skills are playbooks, not document stores. | | External SaaS/API/MCP capabilities | agent/connections/ | Connections hide credentials and expose remote tools. | | Product docs, runbooks, policies, decisions | agent/knowledge/ with eve-knowledge | Reference material should be searched and cited, not stuffed into prompts. | | Runtime-learned user facts | Future memory layer | Mutable memory needs approval, retention, delete, export, and audit rules. |

File Conventions

Supported files:

• Markdown
• MDX
• Plain text
• JSON
• YAML

Markdown frontmatter becomes metadata. Headings become citation context. .eveknowledgeignore adds project-specific ignore rules on top of safe defaults for env files, keys, build output, dependencies, and the local .eve-knowledge/ store.

Config

{
  "knowledgeDir": "agent/knowledge",
  "storeDir": ".eve-knowledge",
  "redaction": {
    "mode": "warn"
  },
  "modelOutput": {
    "maxResults": 5,
    "maxSnippetCharacters": 800,
    "includeCitationsSeparately": true,
    "compact": true
  }
}

index warns on likely secrets by default. check runs with fail-fast redaction semantics for CI.

Executable eve-knowledge.config.ts/js/mjs files are trusted-code only and require --trusted-config. CI should use eve-knowledge.config.json.

modelOutput controls the generated Eve tool's context budget: maximum cited results, snippet length, whether citations are repeated separately, and compact mode.

Embeddings

The MVP uses lexical search so development, tests, and evals work without an embedding provider. The public contracts include EmbeddingProvider and KnowledgeStore so production adapters can add vector search without changing the generated Eve tool.

If you add embeddings, keep provider configuration explicit. Do not silently send private docs to a third-party embedding provider.

CLI

npx eve-knowledge init --dry-run
npx eve-knowledge init --force
npx eve-knowledge index
npx eve-knowledge check
npx eve-knowledge check --production
npx eve-knowledge doctor
npx eve-knowledge doctor --json
npx eve-knowledge doctor --production
npx eve-knowledge search "SOC 2"
npx eve-knowledge search "SOC 2" --explain

init detects Eve projects through agent/instructions.md, agent/agent.ts, agent/tools/, or an eve dependency. Use --allow-non-eve only for tests, templates, or unusual project layouts.

doctor reports Node engine compatibility, Eve project detection, config status, knowledge/index presence, store stats, redaction/check status, storage durability, Vercel/serverless local-filesystem warnings, and suggested next actions.

search --explain keeps normal search output intact unless requested, then adds matched query tokens, matched fields, score, citation, chunk id, and source id/path details.

Evals

import { runKnowledgeEvals } from "eve-knowledge";

const results = await runKnowledgeEvals({
  cases: [
    {
      name: "refund citation",
      query: "refund window",
      expectPath: "agent/knowledge/product/refunds.md",
    },
    {
      name: "no answer",
      query: "HIPAA attestation",
      expectNoResults: true,
    },
  ],
});

Memory Versus Knowledge

Reference knowledge is committed source material. Mutable memory is learned at runtime. eve-knowledge keeps memory disabled by default and does not silently persist user facts.

Future memory support must include provenance, approval, delete, forget, export, retention, and redaction hooks before it becomes a default feature.

Common Examples

Support runbook:

agent/knowledge/runbooks/refunds.md
agent/knowledge/runbooks/escalations.md

Repo decisions:

agent/knowledge/decisions/0001-use-postgres.md
agent/knowledge/decisions/0002-agent-memory-policy.md

Product docs:

agent/knowledge/product/pricing.md
agent/knowledge/product/security.md

Personal memory:

Keep mutable personal memory out of reference docs until you have explicit approval, retention, delete, export, and audit rules. Use committed reference docs for stable facts and policies.

Storage

The built-in local JSON store is for development and tests. For Vercel production, either commit a small read-only index and never write from Functions, or use a tested durable adapter that implements the exported KnowledgeStore contract. See docs/production-storage.md and the deployable template in examples/vercel-eve-support-agent.

Native Eve Knowledge Slot

If Eve later ships a native agent/knowledge/ slot, this package should become the migration bridge:

1. Keep the same folder convention.
2. Reuse existing chunk metadata and citations where possible.
3. Replace the generated search_knowledge tool with Eve's native capability.
4. Keep eve-knowledge check as a CI/eval layer if it remains useful.

Until that exists, agent/knowledge/ is only an eve-knowledge convention.

Privacy

Do not index private customer data, personal data, credentials, or regulated records unless you have consent, retention rules, deletion procedures, and an appropriate production store. The default scanner ignores common secret files and warns on secret-looking content, but those checks are guardrails, not a substitute for data governance.

Troubleshooting

• No Eve project detected: add agent/instructions.md, agent/agent.ts, agent/tools/, or an eve dependency.
• Search returns no results: run npx eve-knowledge index and check .eve-knowledge/index.json.
• CI fails on redaction: remove the unsafe file, add a safe ignore rule, or move sensitive data to a governed system.
• Production warning: do not use local filesystem storage for durable serverless workloads.