intentic-ike 0.3.0

intentic Knowledge Engine — context-efficient knowledge serving for AI agents

ike — intentic Knowledge Engine

Make your Markdown knowledge base queryable by any AI tool — in one command.

pip install intentic-ike[mcp]
ike init --kb-root ./docs

ike scans your docs, fixes quality issues, and generates config files so that Claude Code, Cursor, Codex, Windsurf, and every other AI coding tool can query your knowledge base with precision.

Before ike: Your AI tool reads entire files, wastes context, gets confused. After ike: Your AI tool asks for exactly the section it needs. 77-94% fewer tokens.

# Without ike: 17,490 tokens (4 full files dumped into context)
$ cat company/vision.md company/icp.md company/positioning.md company/messaging.md | wc -w

# With ike: 3,969 tokens (8 targeted sections)
$ ike route "ICP definition"
→ company/icp-definition.md#ideal-customer-profile-icp (2,836 tokens)
$ ike fetch company/icp-definition.md --section ideal-customer-profile-icp

Quick Start

Option A: Let your AI tool do it

Open your AI editor and paste this prompt:

Copy this prompt into Claude Code, Cursor, Codex, or any AI coding tool

I need to set up ike (intentic Knowledge Engine) to make this repository's
documentation queryable by AI tools.

ike is a CLI + MCP server that indexes Markdown files and serves them via
2-step retrieval: route (find relevant sections, ~100 tokens) then fetch
(load specific content). This is much more efficient than reading entire
files — 77-94% token savings.

Repo: https://github.com/pedrams/ike
Docs: https://github.com/pedrams/ike/blob/main/docs/build-with-ai.md

Please do the following:

1. INSTALL: Run `pip install intentic-ike[mcp]`
   - Requires Python 3.12+
   - The [mcp] extra includes the MCP server for IDE integration

2. FIND MY DOCS: Look for the directory containing my Markdown documentation.
   Common locations: ./docs, ./knowledge, ./wiki, or the repo root.
   List the .md files you find so I can confirm.

3. INITIALIZE: Run `ike init --kb-root <path-to-docs>`
   This will:
   - Scan all .md files and report quality (ready/fixable/needs review)
   - Generate .mcp.json (MCP server config for Claude Code, Cursor, etc.)
   - Generate AGENTS.md (universal AI tool discovery file)
   If .mcp.json already exists, ike merges — it won't overwrite your config.

4. FIX DOCS: Run `ike doctor --yes`
   This auto-adds missing YAML frontmatter (title, domain, summary) to docs
   that need it. Only metadata is added — document content is never changed.
   If you prefer to review each fix: run `ike doctor` without --yes.

5. FIX CROSS-REFERENCES: Run `ike doctor --cross-refs`
   This analyzes orphaned documents (no incoming links) and suggests which
   docs should link to each other based on shared domains and keywords.
   For each suggestion:
   - Read both documents to understand their relationship
   - Add a `## Related` section at the bottom with Markdown links,
     or add inline links where they fit naturally in the content
   - Only add links that make semantic sense — skip weak matches
   After adding links, run `ike lint` to verify orphan count decreased.

6. VERIFY: Run these commands and show me the output:
   - `ike route "test"` — should return matching sections with token counts
   - `ike lint` — should show remaining quality issues (if any)
   - `cat .mcp.json` — should show the MCP server config
   - `cat AGENTS.md` — should show the AI tool discovery file

7. DONE: Tell me to restart my AI tool so the MCP connection activates.

If any step fails:
- "ike: command not found" → pip install didn't work, try: python -m ike --help
- "ike serve fails with ImportError" → install with MCP: pip install intentic-ike[mcp]
- "route returns no results" → run: ike index --rebuild
- "doctor changes too much" → use: ike doctor (interactive) instead of --yes

Option B: Manual setup (4 commands)

pip install intentic-ike[mcp]       # 1. Install
cd ~/my-repo
ike init --kb-root ./docs           # 2. Scan docs, generate .mcp.json + AGENTS.md
ike doctor --yes                    # 3. Fix missing frontmatter
ike route "test"                    # 4. Verify
# Restart your AI tool

How It Works

2-step retrieval: Route first (~100 tokens), then fetch only what you need.

# Step 1: Find relevant sections
$ ike route "deployment strategy"
{
  "chunks": [
    {"file_path": "engineering/architecture.md",
     "section_id": "deployment", "score": 3.0, "token_count": 842}
  ]
}

# Step 2: Load only what you need
$ ike fetch engineering/architecture.md --section deployment
## Deployment
CI/CD pipeline deploys to Hetzner Cloud...

The AI tool decides what to load based on token counts. No context wasted.

AI Tool Compatibility

ike generates discovery files for every major AI coding tool:

AI Tool	How it discovers ike	Generated by
Claude Code	.mcp.json + AGENTS.md	ike init
Cursor	.mcp.json + AGENTS.md	ike init
Codex (OpenAI)	AGENTS.md	ike init
Windsurf	.mcp.json + AGENTS.md	ike init
Claude Desktop	.mcp.json	ike init
OpenCode	AGENTS.md	ike init
Hermes	.mcp.json + AGENTS.md	ike init
VS Code + Copilot	.mcp.json	ike init
Zed	.mcp.json	ike init
Aider	AGENTS.md	ike init

MCP tools (for MCP-capable editors): route, fetch, query, lint CLI commands (for everything else): ike route, ike fetch, ike query, ike lint

Commands

Setup

Command	What it does
ike init --kb-root ./docs	Scan docs, generate .mcp.json + AGENTS.md
ike doctor --yes	Auto-fix missing frontmatter
ike doctor	Interactive frontmatter fix (review each)
ike doctor --cross-refs	Suggest missing cross-references for orphans
ike serve	Start MCP server (stdio transport)
ike migrate-mcp	Migrate old .mcp.json to portable format

Query

Command	What it does
ike route "query"	Find relevant sections (~100 tokens response)
ike fetch path/file.md	Load entire file
ike fetch path/file.md --section id	Load specific section
ike query "text" --depth deep	Route + fetch in one step

Maintenance

Command	What it does
ike lint	Check for missing frontmatter, broken refs, orphans
ike lint --freshness 30	Also flag docs older than 30 days
ike list	List all indexed sections
ike index --rebuild	Rebuild search index

Global options

ike --kb-root /path/to/kb route "query"   # custom KB root
export IKE_KB_ROOT=/path/to/kb            # or via env var
ike --version                             # show version

Context Efficiency

Tested against a real 81-doc knowledge base:

Scenario	Without ike	With ike	Savings
Signal analysis (4 company files)	17,490 tokens	3,969 tokens	-77%
Ripple analysis (search KB)	17,716 tokens	2,811 tokens	-84%
Architecture lookup (1 section)	4,299 tokens	259 tokens	-94%
Vision section (from 7K doc)	7,175 tokens	807 tokens	-89%

Every token saved is a token available for reasoning.

Document Format

ike works with any Markdown. For best results, docs should have YAML frontmatter:

---
title: "Authentication Architecture"
domain: "engineering"
summary: "OAuth2 + JWT auth flow for the API gateway."
---

Don't have frontmatter? Run ike doctor --yes — it infers title from H1, domain from directory path, summary from the first paragraph.

Install

pip install intentic-ike          # CLI only
pip install intentic-ike[mcp]     # CLI + MCP server

Requires Python 3.12+. Works on Linux, macOS, Windows (WSL).

MCP Server Configuration

ike init generates .mcp.json automatically. Or configure manually:

{
  "mcpServers": {
    "ike": {
      "command": "ike",
      "args": ["serve"],
      "env": { "IKE_KB_ROOT": "/path/to/your/docs" }
    }
  }
}

Architecture

AI Tool (Claude Code, Cursor, Codex, ...)
        |
   ike CLI / MCP Server
        |
   Engine (facade)
        |
   ┌────┬────┬────┬────┐
Parser Index Fetcher Writer Linter
   |    |
markdown-it  SQLite WAL

• Plugin CLI — Commands auto-discovered from ike/commands/*_cmd.py
• Thread-safe — SQLite with per-thread connections (safe for MCP thread pool)
• Lazy MCP — fastmcp only imported when ike serve runs

Development

git clone https://github.com/pedrams/ike && cd ike
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,mcp]"
pytest                                  # 184 tests, ~5s

License

MIT