Knowledge

Persistent personal knowledge system powered by Graphiti knowledge graph with Neo4j (default) or FalkorDB backend. Automatically extracts entities, relationships, and temporal context from conversations, documents, and ideas.

Workflow Routing

Core Capabilities

Knowledge Graph Features:

• •Automatic Entity Extraction - Identifies people, organizations, locations, concepts, preferences, requirements
• •Relationship Mapping - Tracks how entities connect with temporal context
• •Semantic Search - Finds relevant knowledge using vector embeddings
• •Episode-Based Storage - Preserves context and conversations over time
• •Multi-Source Input - Accepts text, JSON, messages, and structured data

Built-in Entity Types:

• •Preferences - User choices, opinions, configurations
• •Requirements - Features, needs, specifications
• •Procedures - SOPs, workflows, how-to guides
• •Locations - Physical or virtual places
• •Events - Time-bound occurrences, experiences
• •Organizations - Companies, institutions, groups
• •Documents - Articles, reports, books, content

Prerequisites

Required Setup:

The skill is installed at ~/.claude/skills/Knowledge/ (or $PAI_DIR/skills/Knowledge/).

1. •

   Start the Graphiti MCP server:

   bash

   cd ~/.claude/skills/Knowledge
   bun run server-cli start
   

2. •

   Verify server is running:

   bash

   cd ~/.claude/skills/Knowledge && bun run server-cli status
   

3. •

   Other server commands:

   bash

   bun run server-cli stop      # Stop containers
   bun run server-cli restart   # Restart containers
   bun run server-cli logs      # View logs
   bun run server-cli logs --mcp  # MCP server logs only
   bun run server-cli logs --db   # Database logs only
   

4. •

   Configure API key (in PAI .env ~/.claude/.env):

   bash

   MADEINOZ_KNOWLEDGE_OPENAI_API_KEY=sk-your-key-here
   

Interface Priority: CLI-First, MCP-Fallback

ALWAYS use this execution order:

1. •PRIMARY: Knowledge CLI (via Bash) - Reliable, token-efficient, human-readable
2. •FALLBACK: MCP Tools - Only if CLI fails or for programmatic access

Why CLI-first?

• •MCP tools may have session/connection issues in Claude Code
• •CLI provides 25-35% token savings with compact output
• •CLI has better error messages and troubleshooting
• •CLI works reliably via direct Bash execution

Knowledge CLI (Primary Interface)

Run commands from the skill directory:

cd ~/.claude/skills/Knowledge

Commands:

# Add knowledge (REQUIRES both title AND body as separate quoted strings)
bun run tools/knowledge-cli.ts add_episode "Short Title" "Full content body text here" "Source"

# Search entities (30%+ token savings)
bun run tools/knowledge-cli.ts search_nodes "query" 10

# Search relationships (30%+ token savings)
bun run tools/knowledge-cli.ts search_facts "query" 10

# Get recent episodes (25%+ token savings)
bun run tools/knowledge-cli.ts get_episodes 10

# Get system status
bun run tools/knowledge-cli.ts get_status

# Clear graph (destructive - requires --force)
bun run tools/knowledge-cli.ts clear_graph --force

# Check server health
bun run tools/knowledge-cli.ts health

Options:

• •--raw - Output raw JSON instead of compact format
• •--metrics - Display token metrics after each operation
• •--metrics-file <path> - Append metrics to JSONL file
• •--since <date> - Filter results created after this date
• •--until <date> - Filter results created before this date

Temporal Search (date filtering):

# Today's knowledge
bun run tools/knowledge-cli.ts search_nodes "query" --since today

# Last 7 days
bun run tools/knowledge-cli.ts search_facts "query" --since 7d

# Date range
bun run tools/knowledge-cli.ts search_nodes "query" --since 2026-01-01 --until 2026-01-15

Date formats: today, yesterday, 7d, 1w, 1m, or ISO dates (2026-01-26)

What Gets Captured:

• •Conversations and insights from work sessions
• •Research findings and web content
• •Code snippets and technical decisions
• •Project documentation and notes
• •Personal preferences and decisions
• •Meeting notes and action items

Examples

Example 1: Capture a Learning

User: "Remember that when using Podman volumes, you should always mount to /container/path not host/path"

→ Invokes CaptureEpisode workflow → AI extracts title from content and calls CLI with TWO arguments:

bun run tools/knowledge-cli.ts add_episode \
  "Podman Volume Mounting Syntax" \
  "When using Podman volumes, always mount to /container/path not host/path. The left side is host path, right side is container path." \
  "User learning"

→ Stores episode with extracted entities:

• •Entity: "Podman volumes" (Topic)
• •Entity: "volume mounting" (Procedure)
• •Fact: "Podman volumes use /container/path syntax" → User receives: "✓ Captured: Podman volume mounting syntax"

Example 2: Search Knowledge

User: "What do I know about Graphiti?"

→ Invokes SearchKnowledge workflow → Searches knowledge graph for "Graphiti" entities → Returns related entities, facts, and summaries → User receives: "Based on your knowledge graph, Graphiti is..."

Example 3: Find Relationships

User: "How are FalkorDB and Graphiti connected?"

→ Invokes SearchFacts workflow → Searches for edges between FalkorDB and Graphiti entities → Returns facts showing relationship with temporal context → User receives: "FalkorDB is the graph database backend for Graphiti MCP server"

Example 4: Get Recent Learning

User: "What did I learn this week about PAI?"

→ Invokes GetRecent workflow → Retrieves recent episodes mentioning "PAI" or "Personal AI Infrastructure" → Returns chronological list with timestamps → User receives: "Recent additions: 1) PAI skills architecture... 2) Canonical skill structure..."

Example 5: Clear and Reset

User: "Clear my knowledge graph and start fresh"

→ Invokes ClearGraph workflow → Confirms destructive action → Deletes all entities and relationships → Rebuilds indices → User receives: "✓ Knowledge graph cleared. Ready for fresh knowledge capture."

MCP Integration (Fallback Only)

⚠️ Use MCP tools only when CLI fails or for programmatic TypeScript access.

MCP Server Endpoint:

http://localhost:8000/mcp/

Available MCP Tools (Fallback):

Naming Convention (Hybrid Approach):

• •User-facing (Skills/Workflows): Knowledge-friendly language ("store knowledge", "search my knowledge")
• •Internal (TypeScript): Graphiti-native methods (addEpisode, searchNodes, searchFacts)
• •MCP Layer: Actual tool names (add_memory, search_nodes, search_memory_facts)

Response Caching: Search operations (search_nodes, search_memory_facts) are cached to improve performance:

• •TTL: 5 minutes (configurable via cacheTtlMs)
• •Max entries: 100 (configurable via cacheMaxSize)
• •Scope: Per-client instance (not shared across sessions)
• •Cache invalidation: Automatic on TTL expiry, or manual via clearCache()

To disable caching, initialize the client with enableCache: false.

Configuration Options

Environment Variables (set in PAI config: $PAI_DIR/.env or ~/.claude/.env):

# LLM Configuration (OpenRouter recommended)
MADEINOZ_KNOWLEDGE_OPENAI_API_KEY=sk-or-v1-your-key-here
MADEINOZ_KNOWLEDGE_OPENAI_BASE_URL=https://openrouter.ai/api/v1
MADEINOZ_KNOWLEDGE_MODEL_NAME=openai/gpt-4o-mini
MADEINOZ_KNOWLEDGE_LLM_PROVIDER=openai

# Embedder Configuration (Ollama recommended - free & fast)
MADEINOZ_KNOWLEDGE_EMBEDDER_PROVIDER=ollama
MADEINOZ_KNOWLEDGE_EMBEDDER_PROVIDER_URL=http://host.containers.internal:11434
MADEINOZ_KNOWLEDGE_EMBEDDER_MODEL=mxbai-embed-large
MADEINOZ_KNOWLEDGE_EMBEDDER_DIMENSIONS=1024

# Concurrency (adjust based on API tier)
MADEINOZ_KNOWLEDGE_SEMAPHORE_LIMIT=10

# Group ID (for multiple knowledge graphs)
MADEINOZ_KNOWLEDGE_GROUP_ID=main

# Disable telemetry
MADEINOZ_KNOWLEDGE_GRAPHITI_TELEMETRY_ENABLED=false

Model Recommendations:

Via OpenRouter (Recommended):

• •openai/gpt-4o-mini - Most reliable, $0.129/1K ops
• •google/gemini-2.0-flash-001 - Best value, $0.125/1K ops
• •openai/gpt-4o - Fastest, $2.155/1K ops

Direct OpenAI:

• •gpt-4o-mini - Fast, cost-effective for daily use
• •gpt-4o - Better for complex reasoning

⚠️ Known Failures: Llama, Mistral, DeepSeek models fail Graphiti Pydantic validation

Related Documentation

• •${PAI_DIR}/skills/CORE/SkillSystem.md - Canonical skill structure guide
• •${PAI_DIR}/skills/CORE/SYSTEM/MEMORYSYSTEM.md - PAI's memory documentation
• •Graphiti Documentation
• •Podman Configuration

Last Updated: 2026-01-28