Skip to main content

Manual Workflows

For users without Claude Code (or any automation platform)

This guide provides step-by-step workflows for using the knowledge graph system manually. Each workflow includes the exact commands to run and what to fill in at each step.

💡 New to knowledge graphs?

This guide assumes you've completed initial setup. If not:

Using Claude Code? Most of these workflows have a single command equivalent. See COMMAND-GUIDE.md.

Table of Contents​

Quick Start (first-time setup)

  1. Setup

Daily Workflows (regular use) 2. Workflow 1: Create Lesson Learned 3. Workflow 2: Create Architecture Decision Record (ADR) 4. Workflow 3: Extract Chat History 5. Workflow 4: Search Knowledge Base 6. Workflow 5: Create Session Summary

Advanced Workflows (as needed) 7. Workflow 6: Create Meta-Issue 8. Workflow 7: Extract Patterns to Knowledge Graph

Maintenance (monthly/quarterly) 9. Workflow 8: Review and Maintain 10. Workflow 9: Manage MEMORY.md

  1. Tips and Shortcuts

Setup​

1. Initialize Directory Structure​

# Create knowledge graph directories
mkdir -p docs/{lessons-learned/{architecture,debugging,process,patterns},decisions,knowledge,sessions}

# Create placeholder READMEs
for dir in docs/lessons-learned/*/; do
  echo -e "# Category\n\nLessons in this category:\n\n<!-- Add links as you create lessons -->" > "$dir/README.md"
done

# Create main knowledge graph files
touch docs/knowledge/{patterns.md,concepts.md,gotchas.md}

# Add to git
git add docs/
git commit -m "docs: initialize knowledge graph structure"

2. Copy Templates​

# Copy all templates to your project
cp -r core/templates/. docs/templates/

Templates available after copying:

  • docs/templates/lessons-learned/lesson-template.md — For problems solved
  • docs/templates/decisions/ADR-template.md — For important decisions
  • docs/templates/knowledge/entry-template.md — For patterns and concepts
  • docs/templates/sessions/session-template.md — For work session summaries

What are templates? See Template in the Concepts Guide.

Workflow 1: Create Lesson Learned​

When: Solved a non-trivial problem and want to document the solution for future reference.

Claude Code equivalent: /kmgraph:capture-lesson

Step-by-Step​

1. Choose a category based on problem type:

CategoryUse for
architecture/System design, component structure
debugging/Troubleshooting, bug fixes
process/Workflow improvements, tools
patterns/Reusable design patterns

2. Copy template with a meaningful filename:

cp docs/templates/lessons-learned/lesson-template.md \
   docs/lessons-learned/process/Database_Connection_Pooling.md

3. Fill in the template — open the file and fill in [MANUAL] fields:

---
title: "Lesson: Database Connection Pooling"  # [MANUAL]
category: process                              # [MANUAL]
tags: [database, performance, pooling]         # [MANUAL]
# [AUTO] fields (created, author, git.*) filled by command; leave blank manually
---

Then write the body — answer these four questions:

  • Problem: What went wrong?
  • Root Cause: Why did it happen?
  • Solution: What fixed it (step by step)?
  • Prevention: How to avoid this in the future?

4. Update the category README — open docs/lessons-learned/process/README.md and add a link:

- [Database Connection Pooling](./Database_Connection_Pooling.md) - Fixing connection exhaustion

5. (Optional) Extract reusable pattern to knowledge graph — see Workflow 7.

6. Commit:

git add docs/lessons-learned/process/Database_Connection_Pooling.md
git add docs/lessons-learned/process/README.md
git commit -m "docs: add lesson on database connection pooling"

Why document immediately? Details are freshest right after solving the problem. Documenting later means forgetting the root cause and key steps.

Workflow 2: Create Architecture Decision Record (ADR)​

When: Making an architectural decision that affects multiple people or components — something a future team member might ask "why did the team do it this way?"

Claude Code equivalent: /kmgraph:capture-lesson (with ADR category)

What is an ADR? See ADR in the Concepts Guide.

Step-by-Step​

1. Find the next ADR number:

ls docs/decisions/ | grep "ADR-"
# Example: ADR-001-dual-format-docs.md, ADR-002-skills-architecture.md
# → Next number: ADR-003

2. Copy template with numbered filename:

cp docs/templates/decisions/ADR-template.md \
   docs/decisions/ADR-003-connection-pooling.md

3. Fill in the template — focus on these four sections:

  • Context: Why was this decision needed?
  • Options: What alternatives were considered? (list 2–4 options)
  • Decision: What was chosen and why?
  • Consequences: What are the expected positive and negative outcomes?

4. Update ADR index — open docs/decisions/README.md and add:

- [ADR-003: Connection Pooling Strategy](./ADR-003-connection-pooling.md) - Accepted

5. Link from related lessons (optional) — in the lesson file's Cross-References section:

- **ADR:** [[../../decisions/ADR-003-connection-pooling.md]]

6. Commit:

git add docs/decisions/ADR-003-connection-pooling.md
git commit -m "docs(adr): ADR-003 connection pooling strategy"

Workflow 3: Extract Chat History​

When: A productive AI conversation contains insights worth preserving in the knowledge graph.

Platform: Claude Code or Gemini/Antigravity

Run Extraction Script​

Claude Code:

python3 core/scripts/extract_claude.py
# Output: chat-history/YYYY-MM/YYYY-MM-DD-claude.md

Gemini/Antigravity:

python3 core/scripts/extract_gemini.py
# Output: chat-history/YYYY-MM/YYYY-MM-DD-gemini.md

Review and Extract Knowledge​

Read the extracted chat and identify content to preserve:

Found in chatAction
Problem-solving session→ Create Lesson Learned (Workflow 1)
Architectural discussion→ Create ADR (Workflow 2)
Reusable pattern discovered→ Update Knowledge Graph (Workflow 7)

When creating a lesson from a chat, reference the source:

**Source:** chat-history/2024-10/2024-10-15-claude.md

Workflow 4: Search Knowledge Base​

When: Looking for a previously documented solution, pattern, or decision.

Claude Code equivalent: /kmgraph:recall

Search All Knowledge​

# Search across all docs
grep -r "connection pool" docs/

# Search with context (3 lines before/after match)
grep -r -C 3 "connection pool" docs/

Search by Category or Tag​

# Find all architecture lessons
ls docs/lessons-learned/architecture/

# Find all lessons tagged #performance
grep -r "#performance" docs/lessons-learned/

Search Knowledge Graph Files​

# Browse all patterns (section headers)
grep -A 5 "^## " docs/knowledge/patterns.md

# Find specific pattern
grep -A 10 "Connection Pooling" docs/knowledge/patterns.md

# All gotchas
grep -A 5 "^## " docs/knowledge/gotchas.md

Workflow 5: Create Session Summary​

When: End of a significant work session — major debugging, architecture discussion, or sprint.

Claude Code equivalent: /kmgraph:session-summary

What is a session summary? See Session Summary in the Concepts Guide.

Step-by-Step​

1. Create session file organized by month:

mkdir -p docs/sessions/2024-10
cp docs/templates/sessions/session-template.md \
   docs/sessions/2024-10/session-2024-10-15.md

2. Fill in the four main sections:

## Overview
[1-2 sentences: what did this session accomplish?]

## Built
- [Concrete deliverable 1]
- [Concrete deliverable 2]

## Decided
- [Key decision] (see ADR-003)

## Learned
- [Insight that changes future approach]

## Next
- [First concrete next action]

3. Commit:

git add docs/sessions/2024-10/session-2024-10-15.md
git commit -m "docs(session): session summary for 2024-10-15"

Workflow 6: Create Meta-Issue​

When: A complex problem has required multiple solution attempts with evolving understanding — the problem is not yet resolved or just resolved after several attempts.

Claude Code equivalent: /kmgraph:meta-issue

What is a meta-issue? See Meta-Issue in the Concepts Guide.

Step-by-Step​

1. Create the meta-issue directory structure:

mkdir -p docs/meta-issues/performance-degradation/{attempts,analysis}

2. Copy core files from templates:

cp core/templates/meta-issue/README-template.md \
   docs/meta-issues/performance-degradation/README.md
cp core/templates/meta-issue/description-template.md \
   docs/meta-issues/performance-degradation/description.md
cp core/templates/meta-issue/implementation-log-template.md \
   docs/meta-issues/performance-degradation/implementation-log.md
cp core/templates/meta-issue/test-cases-template.md \
   docs/meta-issues/performance-degradation/test-cases.md

3. Create first attempt directory:

mkdir docs/meta-issues/performance-degradation/attempts/001-caching
cp core/templates/meta-issue/solution-approach-template.md \
   docs/meta-issues/performance-degradation/attempts/001-caching/solution-approach.md
cp core/templates/meta-issue/attempt-results-template.md \
   docs/meta-issues/performance-degradation/attempts/001-caching/attempt-results.md

4. Document as the investigation progresses:

StageAction
Before attemptFill in solution-approach.md
During attemptUpdate implementation-log.md with daily progress
After attemptFill in attempt-results.md with outcome
If failedCreate next attempt directory (002-*)
When resolvedUpdate description.md with final understanding

5. Extract lesson when resolved:

cp docs/templates/lessons-learned/lesson-template.md \
   docs/lessons-learned/debugging/Performance_Degradation_Resolution.md

Add cross-reference to the lesson:

**Meta-Issue:** [[../meta-issues/performance-degradation/README.md]]

See META-ISSUE-GUIDE.md for a detailed guide.

Workflow 7: Extract Patterns to Knowledge Graph​

When: A lesson contains a reusable pattern, concept, or common pitfall worth preserving as a quick-reference entry.

Claude Code equivalent: /kmgraph:update-graph

Extract a Pattern​

1. Identify the reusable element in the lesson:

# In the lesson body:
## Solution
Implemented connection pooling with: pool size 20, idle timeout 30s, max wait 10s.

2. Add to docs/knowledge/patterns.md:

## Connection Pooling Pattern

**Problem:** Per-request connections don't scale under load

**Solution:** Maintain a pool of reusable connections

**Quick Reference:**
- Pool size: 10–20 per instance
- Idle timeout: 30–60s
- Max wait: 5–10s
- Monitor: utilization, wait time, errors

**When to use:** High throughput (>100 req/sec), when connection overhead is noticeable

**Cross-References:**
- **Lesson:** [[lessons-learned/process/Database_Connection_Pooling.md]]
- **ADR:** [[decisions/ADR-003-connection-pooling.md]]

Extract a Gotcha​

If the lesson reveals a common pitfall, add it to docs/knowledge/gotchas.md:

## CI Connection Exhaustion

**Symptom:** Tests pass locally, fail in CI with "too many connections"

**Root Cause:** CI runs tests in parallel; local runs sequentially. Parallel execution
multiplies connection usage.

**Fix:** Increase pool size for CI environment specifically

**Cross-References:**
- **Lesson:** [[lessons-learned/debugging/CI_Connection_Issues.md]]

Workflow 8: Review and Maintain​

Frequency: Monthly or quarterly

Check for Stale Content​

# Find lessons not modified in over a year
find docs/lessons-learned -name "*.md" -mtime +365

For each stale lesson, ask:

  • Is the solution still accurate?
  • Is it still the recommended approach?
  • Should it be updated or archived?

Consolidate Duplicates​

# Search for similar topics
grep -r "connection pool" docs/lessons-learned/

If multiple lessons cover the same topic, either consolidate into one comprehensive lesson or keep both and cross-reference them.

Archive Old Sessions​

# Move old sessions to archive
mkdir -p docs/sessions/archive
mv docs/sessions/2022-* docs/sessions/archive/

Workflow 9: Manage MEMORY.md​

When: MEMORY.md is approaching the token budget limit (~1,500 tokens / ~200 lines) or archived knowledge needs to be retrieved.

Claude Code equivalent: /kmgraph:archive-memory and /kmgraph:restore-memory

What is MEMORY.md? See MEMORY.md in the Concepts Guide.

Part A: Archive Stale Entries​

1. Check current size:

MEMORY_PATH="$HOME/.claude/projects/$(basename $(pwd))/memory/MEMORY.md"
words=$(wc -w < "$MEMORY_PATH")
echo "Current size: ~$((words * 13 / 10)) tokens (target: <1,500)"

2. Identify entries to archive — look for:

  • Entries last referenced more than 90 days ago
  • Historical context no longer relevant to active work

3. Move stale entries:

  • Copy the full section (heading + content) from MEMORY.md to MEMORY-archive.md
  • Remove the section from MEMORY.md
  • Add an archive log entry noting what was archived and when

4. Commit both files:

git add memory/MEMORY*.md
git commit -m "docs(memory): archive stale entries (~X tokens freed)"

Part B: Restore Archived Entries​

1. View archived entries:

grep "^### " memory/MEMORY-archive.md

2. Copy the needed entry back to the appropriate section of MEMORY.md.

3. Mark the restoration in the archive log and commit both files.

Decision Guide​

SituationAction
MEMORY.md > 1,500 tokensArchive oldest entries
Working on a related problemRestore relevant archived entry
Entry > 90 days old, not neededLeave archived

Tips and Shortcuts​

Shell Aliases​

Add to ~/.bashrc or ~/.zshrc:

alias lesson='cp docs/templates/lessons-learned/lesson-template.md'
alias kg-search='grep -r'
alias kg-patterns='cat docs/knowledge/patterns.md'
alias last-adr='ls docs/decisions/ | grep ADR | tail -1'

Editor Template Shortcuts​

Vim (~/.vimrc): command! Lesson r ~/.templates/lesson-template.md

VSCode: Create file snippets in settings.json to insert template content with a keyword shortcut.