Skip to main content

Configuration

This guide covers configuring and customizing the Knowledge Management Graph after installation.

Installation instructions: See GETTING-STARTED.md for installation steps.

Optional: Copy Example Content​

The plugin includes examples you can study or adapt:

# View examples (don't copy to your project yet)
ls core/examples/knowledge/
ls core/examples/lessons-learned/
ls core/examples/decisions/

# Study the examples
cat core/examples/knowledge/sample-patterns.md
cat core/examples/lessons-learned/process/Example_Chat_History_Workflow.md

Recommendation: Study examples first, then create your own entries. Don't copy examples directly (they're generalized, not project-specific).

Integration with Existing Projects​

If you're adding this to an established project:

1. Preserve Existing Documentation​

# If you have existing docs/ directory, move knowledge system elsewhere
mkdir -p .knowledge/
# Use .knowledge/ instead of docs/ for knowledge graph

Or integrate into existing structure:

# Add knowledge subdirectories to existing docs/
mkdir -p docs/knowledge-graph/{lessons-learned,decisions,knowledge,sessions}

Create knowledge graph entries that reference your existing docs:

# In docs/knowledge/patterns.md

## Existing Authentication Pattern

**Quick Summary:** OAuth2 implementation with refresh tokens

**Details:** See detailed guide at [docs/auth/oauth-guide.md](../auth/oauth-guide.md)

**Cross-References:**
- **Related Lesson:** [[lessons-learned/security/oauth-implementation.md]]

3. Extract Knowledge Gradually​

Don't try to document everything at once:

  • Start with new work (document as you go)
  • Extract valuable past knowledge opportunistically
  • Let the system grow organically

Team Workflows​

For Solo Developers​

The knowledge graph is your project memory. Use it for:

  • Capturing solutions to non-trivial problems
  • Recording architectural decisions
  • Building reusable patterns library
  • Maintaining context across weeks/months

For Small Teams (2-5 people)​

Workflow:

  1. Each developer creates lessons/ADRs locally
  2. Commit to feature branches
  3. Review during PR (knowledge is code)
  4. Merge to main

Team conventions:

# In docs/knowledge/README.md

## Team Conventions

- **Lessons:** Create after solving non-trivial problems
- **ADRs:** Required for architectural decisions affecting >1 person
- **Knowledge Graph:** Extract from lessons (don't write directly)
- **Sessions:** Optional (personal preference)

For Larger Teams (6+ people)​

Assign a knowledge curator:

  • Reviews new knowledge entries for clarity
  • Identifies duplicate/overlapping content
  • Suggests consolidation
  • Maintains category READMEs

Weekly knowledge sync meeting (15-30 min):

  • Share recent valuable lessons
  • Discuss emerging patterns
  • Update team on architectural decisions
  • Identify gaps in documentation

Privacy & Public Sharing​

⚠️ IMPORTANT: The knowledge graph may contain sensitive information.

Before Sharing Publicly​

Run sanitization checklist:

# Check for sensitive data
grep -r "api[_-]key\|password\|secret" docs/
grep -r "/Users/\|/home/\|C:\\\\" docs/
grep -r "@yourcompany.com" docs/

# See full checklist
cat core/docs/SANITIZATION-CHECKLIST.md

Use Pre-Commit Hook​

Install sanitization hook to catch issues before commit:

cp core/examples-hooks/pre-commit-sanitization.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Customize patterns for your project
vim .git/hooks/pre-commit

See core/docs/SANITIZATION-CHECKLIST.md for details.

MCP Server Setup (Optional)​

Enable knowledge graph as MCP server for broader access:

1. Install MCP SDK​

npm install @anthropic/mcp

2. Configure MCP Server​

// claude_desktop_config.json
{
  "mcpServers": {
    "knowledge-graph": {
      "command": "node",
      "args": ["core/mcp-server.js"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

3. Test Connection​

# Start MCP server manually to test
node core/mcp-server.js

# Should see: "MCP server listening..."

See core/docs/PLATFORM-ADAPTATION.md#mcp-server for troubleshooting.

Notification Webhooks (Optional)​

KMGraph can send a notification to a Slack channel or any webhook endpoint whenever a lesson or ADR is saved. This feature is off by default — no configuration is required unless you want it.

How to enable​

1. Get a webhook URL

  • Slack: Go to api.slack.com/apps, create an app, enable Incoming Webhooks, and copy the generated URL.
  • Other services: Any service that accepts an HTTP POST with a JSON body works (Discord, Teams, custom endpoints, etc.).

2. Set the webhook URL

Add it to your shell environment or .env file in your project root:

# In your shell profile (~/.zshrc or ~/.bashrc)
export KMGRAPH_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

# Or in a .env file in your project root (make sure .env is in .gitignore)
KMGRAPH_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

Note: docs/sessions/ and .env are gitignored by default. Never commit a webhook URL to version control.

3. Verify it works

After capturing your next lesson or ADR, you should receive a notification within a few seconds. If nothing arrives, check that the URL is correctly exported in your current shell session.

What the notification contains​

{
  "text": "📝 KMGraph: New lesson captured — 'JWT Timestamp Unit Mismatch' in docs/lessons-learned/"
}

The message includes the entry type, title, and file path. No file contents are sent.

Disabling webhooks​

Unset the environment variable:

unset KMGRAPH_WEBHOOK_URL

Or remove KMGRAPH_WEBHOOK_URL from your .env file.

Templates​

Customize document templates for your workflow:

# Edit templates (changes affect NEW documents only)
vim core/templates/lessons-learned/lesson-template.md
vim core/templates/decisions/ADR-template.md

Categories​

Add custom categories:

# Create new category
mkdir -p docs/lessons-learned/security
touch docs/lessons-learned/security/README.md

# Update auto-detection in skills
vim .claude/skills/knowledge-capture.md
# Add "security" keywords to category mapping

Workflows​

Modify skills to match your process:

# Copy skill to global (for execution)
vim ~/.claude/commands/knowledge-capture.md

# Edit workflow steps
# Save and restart Claude Code

Troubleshooting​

Skills Don't Appear in Menu​

Cause: Skills load at startup only

Fix: Restart Claude Code completely (quit and relaunch)

Skills Execute but Don't Work​

Cause: Skills in wrong location or outdated

Fix:

# Verify skills in global directory
ls ~/.claude/commands/knowledge-*

# Re-copy from plugin
cp .claude/skills/knowledge-*.md ~/.claude/commands/
# Restart Claude Code

Knowledge Graph Feels Overhead​

Cause: Trying to document everything

Solution: Be selective:

  • ✅ DO document: Non-obvious solutions, architectural decisions, discovered patterns
  • ❌ DON'T document: Obvious changes, standard practices, routine bug fixes

Quality > Quantity. 5 valuable lessons > 50 routine entries.

Team Not Adopting​

Causes:

  • Too much friction (skills not working)
  • Unclear value (show examples)
  • No reinforcement (mention in code reviews)

Solutions:

  • Reduce friction: Ensure skills work reliably
  • Show value: Share how knowledge graph helped solve problem
  • Gentle reinforcement: "This would make a great lesson learned" in reviews
  • Lead by example: Senior devs use it consistently

Next Steps​

Getting started​

Learning​

Advanced​

---

Need help? Check the examples or adapt the templates to your workflow.