Claude Code Integration

Integrate TruthKeeper with Claude Code to give your AI assistant verified, persistent memory that knows when its knowledge becomes outdated.

Overview

Claude Code is Anthropic's AI coding assistant. By integrating with TruthKeeper, Claude Code can:

  • Remember facts about your codebase across sessions
  • Know when those facts become outdated due to code changes
  • Provide confidence scores for its assertions
  • Maintain an audit trail of what it learned and when

Installation

1. Install TruthKeeper

pip install truthkeeper

2. Start the TruthKeeper Server

truthkeeper serve

3. Configure Claude Code

Add TruthKeeper as an MCP server in your Claude Code settings:

{
  "mcpServers": {
    "truthkeeper": {
      "command": "truthkeeper",
      "args": ["mcp"],
      "env": {
        "TRUTHKEEPER_URL": "http://localhost:8000"
      }
    }
  }
}

MCP Tools

TruthKeeper exposes the following MCP tools to Claude Code:

truthkeeper_remember

Store a new claim about the codebase:

{
  "name": "truthkeeper_remember",
  "arguments": {
    "content": "The UserService class handles authentication via JWT",
    "evidence": {
      "source": "file://src/services/user.py",
      "excerpt": "class UserService:\n    def authenticate(self, token: str):"
    },
    "dependency": {
      "target": "file://src/services/user.py",
      "type": "HARD"
    }
  }
}

truthkeeper_recall

Search for relevant claims:

{
  "name": "truthkeeper_recall",
  "arguments": {
    "query": "authentication",
    "min_confidence": 0.8,
    "limit": 10
  }
}

truthkeeper_check

Verify if a claim is still valid:

{
  "name": "truthkeeper_check",
  "arguments": {
    "claim_id": "clm_abc123"
  }
}

truthkeeper_forget

Mark a claim as outdated:

{
  "name": "truthkeeper_forget",
  "arguments": {
    "claim_id": "clm_abc123",
    "reason": "Function was removed in refactoring"
  }
}

Usage Patterns

Learning During Analysis

When Claude Code analyzes your codebase, it can store what it learns:

User: What does the PaymentService do?

Claude Code:
1. Reads src/services/payment.py
2. Analyzes the code
3. Calls truthkeeper_remember with findings:
   - "PaymentService validates credit cards before charging"
   - "PaymentService uses Stripe API for processing"
   - "PaymentService logs all transactions to audit table"
4. Returns answer to user

Next session:
User: How does payment processing work?

Claude Code:
1. Calls truthkeeper_recall("payment processing")
2. Gets verified claims from previous analysis
3. Answers immediately without re-reading all files

Handling Stale Knowledge

When code changes, TruthKeeper marks affected claims as stale:

Developer: I refactored authentication to use OAuth instead of JWT

*Developer makes changes and commits*

*TruthKeeper detects file changes*
*Marks claims depending on auth files as STALE*

Next session:
User: How does authentication work?

Claude Code:
1. Calls truthkeeper_recall("authentication")
2. Gets claim: "UserService uses JWT" (state: STALE)
3. Knows this information may be outdated
4. Re-reads the files to get current state
5. Updates TruthKeeper with new claims
6. Returns accurate answer

Best Practices

What to Remember

  • Architecture decisions: “We use hexagonal architecture”
  • Conventions: “All API endpoints are in src/api/routes/”
  • Key relationships: “UserService depends on AuthService”
  • Business logic: “Orders over $1000 require manager approval”

What NOT to Remember

  • Implementation details that change frequently
  • Line numbers (they change on every edit)
  • Temporary debugging information
  • User preferences (use a different store)

Dependency Types

  • HARD: For claims that quote specific code
  • SOFT: For claims about patterns or conventions
  • DERIVED: For computed summaries

Hooks Integration

Use Claude Code hooks to automatically sync with TruthKeeper:

{
  "hooks": {
    "preCommit": [
      "truthkeeper source-changed --path ."
    ],
    "postToolUse": [
      {
        "tool": "Read",
        "command": "truthkeeper watch-file $FILE_PATH"
      }
    ]
  }
}

Example Workflow

# Session 1: Initial learning

User: Help me understand this codebase

Claude Code:
- Explores the codebase
- Stores 47 claims about architecture, patterns, key files
- All claims are verified and marked SUPPORTED

# Session 2: Next day, code has changed

Developer pushed refactoring overnight
TruthKeeper detected changes, marked 12 claims STALE

User: Add a new API endpoint for user preferences

Claude Code:
- Recalls claims about API structure (SUPPORTED)
- Recalls claim about auth middleware (STALE)
- Re-verifies the stale claim
- Updates: auth middleware moved to new file
- Implements endpoint with correct patterns

Troubleshooting

Claims not being stored

# Check TruthKeeper is running
curl http://localhost:8000/api/v1/health

# Check MCP connection
claude-code --mcp-debug

Stale claims not detected

# Ensure file watcher is running
truthkeeper watch --path . --verbose

# Manually trigger source change
truthkeeper source-changed --path src/auth.py

Next Steps