### Install Dependencies with npm

Source: https://github.com/jgwill/coaia-spiral/blob/main/2508071957.llmcon.claude.coaia-memory.Extendingmcp-knowledge-graph.txt

Executes the npm install command within the project directory to download and install all necessary project dependencies. This step is crucial after configuration changes to ensure the project has the required packages to build and run.

```bash
cd /media/jgi/F/Dropbox/jgt/edu/llm_mastery/arenas_250706/mcp-knowledge-graph && npm install
```

--------------------------------

### Local Development Setup for COAIA Memory

Source: https://github.com/jgwill/coaia-spiral/blob/main/RELEASE.md

Instructions for setting up COAIA Memory locally. This involves cloning the repository, navigating to the directory, installing dependencies, and building the project.

```bash
git clone <repository>
cd coaia-memory
npm install
npm run build
```

--------------------------------

### Install and Build Project Dependencies

Source: https://github.com/jgwill/coaia-spiral/blob/main/CLAUDE.md

This snippet demonstrates the standard commands for installing project dependencies, building the project, and running tests using npm. It's essential for setting up the development environment.

```bash
npm install
npm run build
node test-coaia.js
```

--------------------------------

### Example: Storytelling Application Integration (CLI)

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-coaiapy-cli-guide.md

Demonstrates the CLI usage pattern for a storytelling application, showing how to initialize a session, create a trace, and add observations for narrative milestones.

```bash
# Initialize storytelling session
coaia fuse sessions create story_session_2025_09_08

# Create trace for the narrative journey  
coaia fuse traces create narrative_trace_001

# Document major story milestones
coaia fuse traces add-observation outline_created narrative_trace_001
coaia fuse traces add-observation chapter1_drafted narrative_trace_001
coaia fuse traces add-observation revision_complete narrative_trace_001
```

--------------------------------

### Build and Test Project with npm

Source: https://github.com/jgwill/coaia-spiral/blob/main/README.md

Provides the necessary commands to install project dependencies and build the application using npm. This is a standard step for developers working with Node.js projects.

```bash
npm install
npm run build
```

--------------------------------

### Python: Storytelling Prompt Example

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

This Python snippet illustrates how to craft a prompt for creative storytelling using the Claude SDK. It emphasizes framing the request around creation rather than problem-solving and includes a detailed prompt with narrative elements, demonstrating how to initialize the client with system prompts and context sources.

```python
# NOT: "Help me fix my plot holes"
# YES: "Help me create a cohesive plot structure"

prompt = """I want to create a compelling narrative where:
- A reluctant hero discovers hidden power
- They must choose between personal desire and community need
- The resolution honors both the external quest and internal transformation

What structural elements will strengthen this vision?"""

async with ClaudeSDKClient(options=ClaudeAgentOptions(
    system_prompt=storytelling_system_prompt,
    setting_sources=["project"]  # Load project context
)) as client:
    await client.query(prompt)
```

--------------------------------

### Create Minimal Project Structure (Bash)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/placeholder.md

Creates a new directory for the package and navigates into it. This is the initial step for setting up a new NPM project.

```bash
mkdir mcp-knowledge-base
cd mcp-knowledge-base
```

--------------------------------

### Python: Streaming Input with Image Support

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

This example shows how to use streaming input with the Claude SDK, which is recommended for dynamic message queuing and supports sending images. It defines an asynchronous generator that yields messages, including a follow-up message with an image, and then processes the query response.

```python
async def message_generator():
    # First message
    yield {
        "type": "user",
        "message": {
            "role": "user",
            "content": "Start a story"
        }
    }
    
    # Wait for conditions
    await asyncio.sleep(2)
    
    # Follow-up with image (streaming input only)
    yield {
        "type": "user",
        "message": {
            "role": "user",
            "content": [
                {"type": "text", "text": "Review this visual"},
                {"type": "image", "source": {
                    "type": "base64",
                    "media_type": "image/png",
                    "data": image_data
                }}
            ]
        }
    }

async for message in query({
    "prompt": message_generator(),
    "options": ClaudeAgentOptions(max_turns=10)
}):
    if message.type == "result":
        print(message.result)
```

--------------------------------

### Python SDK: Handling JSON Output

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-sdk.gemini.md

Demonstrates how to use the Python SDK to get and parse JSON output from the agent. This is crucial for programmatic consumption of agent results.

```python
from tools.claude import CLINotFoundError, ProcessError, ClaudeSDKClient

async def get_json_output():
    try:
        async with ClaudeSDKClient() as client:
            response = await client.message(
                "This is a test.", output_format="json"
            )
            # Assuming response object has attributes like result, total_cost_usd, session_id
            print(f"Result: {response.result}")
            print(f"Total Cost: {response.total_cost_usd}")
            print(f"Session ID: {response.session_id}")
    except CLINotFoundError:
        print("Error: Claude CLI not found.")
    except ProcessError as e:
        print(f"Error processing request: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")
```

--------------------------------

### Initialize NPM Package (Bash)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/placeholder.md

Initializes a new NPM project by creating a package.json file with default values. The '-y' flag accepts all defaults.

```bash
npm init -y
```

--------------------------------

### Create Minimal index.js (JavaScript)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/placeholder.md

Creates a basic entry point file for the Node.js package. This file is executed when the package is run as a script or imported.

```javascript
console.log('MCP Knowledge Base - Coming Soon');
```

--------------------------------

### Create README.md (Markdown)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/placeholder.md

Provides documentation for the package, explaining its purpose, current status, and future plans. This is essential for users and maintainers.

```markdown
# MCP Knowledge Base

> [!NOTE]
> This package is currently in development. Future versions will provide knowledge base functionality for AI models that support the Model Context Protocol (MCP).

## Coming Soon

This package will build upon mcp-knowledge-graph to provide:
- Enhanced knowledge base capabilities
- Improved memory management
- Advanced querying features

## Status

This is a placeholder release. Production version coming soon.
```

--------------------------------

### Python: Scene Visualization Agent Configuration

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

This Python snippet sets up a 'Scene Visualization' agent. The configuration features a system prompt that guides the agent to create vivid, sensory-rich descriptions, focusing on details, emotional resonance, action, and atmosphere. It specifies the 'Write' tool and a maximum of 6 turns.

```python
scene_agent = ClaudeAgentOptions(
    system_prompt="""You are a Scene Visualizer creating vivid, sensory-rich narrative descriptions.    
Focus:
- Sensory details (sight, sound, smell, touch, taste)
- Emotional resonance of settings
- Dynamic action sequences
- Atmospheric tension    
Create scenes readers will visualize.""",
    allowed_tools=["Write"],
    max_turns=6
)
```

--------------------------------

### Launch Test Environment with claude-code

Source: https://github.com/jgwill/coaia-spiral/blob/main/README.md

Details the command to launch the test environment, which includes a pre-configured MCP setup. This is used for testing the application's functionality in an isolated environment.

```bash
cd test-environment
claude-code  # Launch with pre-configured MCP setup
```

--------------------------------

### Install Claude Agent SDK (TypeScript/JavaScript)

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

Installs the latest production-ready Claude Agent SDK for TypeScript/JavaScript using npm. This package replaces the deprecated '@anthropic-ai/claude-code' package.

```bash
npm install @anthropic-ai/claude-agent-sdk
```

--------------------------------

### Install Claude Agent SDK (Python)

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

Installs the latest production-ready Claude Agent SDK for Python using pip. This is the recommended package for new projects, replacing the deprecated 'claude-code-sdk'.

```bash
pip install claude-agent-sdk
```

--------------------------------

### List Installed GitHub Hooks API Endpoint and Response

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-jgwill-miadi-issue-115-github-hooks-issues-subissues.md

This describes the GET endpoint for retrieving a list of installed GitHub hooks. The response includes the directory where hooks are located, a list of hook event types, and the total count. It clarifies that hooks are executed upon matching webhook events.

```json
{
  "hooksDirectory": "/a/src/Miadi-18/.github-hooks",
  "installedHooks": ["push", "issues", "issue_comment", "sub_issues"],
  "count": 4,
  "description": "Hooks are executed when matching GitHub webhook events are received"
}
```

--------------------------------

### GET /api/hooks/list

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-jgwill-miadi-issue-115-github-hooks-issues-subissues.md

Retrieves a list of all installed hooks within the project. This endpoint provides information about the hooks directory and the names of the hooks that are currently configured and available for execution.

```APIDOC
## GET /api/hooks/list

### Description
Retrieves a list of all installed hooks within the project. This endpoint provides information about the hooks directory and the names of the hooks that are currently configured and available for execution.

### Method
GET

### Endpoint
/api/hooks/list

### Parameters
No parameters required.

### Response
#### Success Response (200)
- **hooksDirectory** (string) - The path to the directory where hooks are stored.
- **installedHooks** (array) - A list of strings, where each string is the name of an installed hook.
- **count** (integer) - The total number of installed hooks.
- **description** (string) - A brief explanation of what hooks are and their purpose.

#### Response Example
```json
{
  "hooksDirectory": "/a/src/Miadi-18/.github-hooks",
  "installedHooks": ["push", "issues", "issue_comment", "sub_issues"],
  "count": 4,
  "description": "Hooks are executed when matching GitHub webhook events are received"
}
```
```

--------------------------------

### Search Operations in CreatingYourLifeCourse

Source: https://github.com/jgwill/coaia-spiral/blob/main/2508071957.llmcon.claude.coaia-memory.Extendingmcp-knowledge-graph.txt

Demonstrates search operations using patterns and paths within the 'CreatingYourLifeCourse' directory. These operations identify relevant files for 'Structural Tension Chart', 'Action Plan', and 'Advancing Structure/Pattern'.

```Shell
● Search(pattern: "Structural Tension Chart", path: "../CreatingYourLifeCourse")
  ⎿  Found 3 files (ctrl+r to expand)

● Search(pattern: "Action Plan", path: "../CreatingYourLifeCourse")
  ⎿  Found 1 file (ctrl+r to expand)

● Search(pattern: "Advancing.*[sS]tructure|Advancing.*[pP]attern", path:
        "../CreatingYourLifeCourse")
  ⎿  Found 3 files (ctrl+r to expand)
```

--------------------------------

### System Configuration Commands

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-coaiapy-cli-guide.md

Commands for initializing and configuring the creative ecosystem.

```APIDOC
## System Configuration Commands

### `init`

#### Description
Initialize creative ecosystem. Sets up foundational configuration for creative workflows and prepares the environment for intelligent automation.
```

--------------------------------

### Using the Pipeline CLI for Template Management

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-coaiapy-cli-guide.md

Illustrates common commands for interacting with the coaia pipeline command-line interface. This includes listing, showing, creating, and initializing workflow templates, enabling powerful automation.

```bash
# Explore available templates with descriptions
pipeline list

# Inspect template structure and variables
pipeline show <template>

# Execute template with parameters
pipeline create <template> --var key=value

# Create new custom templates
pipeline init <name>
```

--------------------------------

### Cheat Sheet: Common JQ Patterns for Hooks

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-jgwill-miadi-issue-115-github-hooks-issues-subissues.md

A collection of frequently used JQ command patterns for parsing JSON payloads in webhook handlers. Examples include extracting fields with defaults, getting array lengths, accessing nested objects, and extracting specific array elements.

```bash
# Extract with default
FIELD=$(echo "$PAYLOAD" | jq -r '.path.to.field // "default"')

# Extract number with 0 default
NUMBER=$(echo "$PAYLOAD" | jq -r '.issue.number // 0')

# Extract array length
COUNT=$(echo "$PAYLOAD" | jq '.commits | length')

# Extract nested object
AUTHOR=$(echo "$PAYLOAD" | jq -r '.issue.user.login // "unknown"')

# Extract first element of array
LABEL=$(echo "$PAYLOAD" | jq -r '.issue.labels[0].name // "none"')
```

--------------------------------

### Restrict Agent Tools and Permissions in Python

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-claude-agent-sdk-v2.md

This Python code demonstrates how to restrict the tools available to agents and set their permission modes for enhanced security. It shows examples of creating `ClaudeAgentOptions` for a read-only agent with specific allowed tools and a 'plan' permission mode, and a creation agent with broader tool access and an 'acceptEdits' permission mode.

```python
# Different permission levels for different agents
read_only_agent = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep"],
    permission_mode="plan"  # Only propose, don't execute
)

creation_agent = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Execute"],
    permission_mode="acceptEdits"  # Execute immediately
)
```

--------------------------------

### NPX Installation for COAIA Memory

Source: https://github.com/jgwill/coaia-spiral/blob/main/RELEASE.md

Installs and runs COAIA Memory using NPX, specifying a path for memory data. This is the recommended installation method for users.

```bash
npx coaia-memory --memory-path ./my-charts.jsonl
```

--------------------------------

### COAIA CLI: Initialize Creative Ecosystem

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-coaiapy-cli-guide.md

The 'init' command initializes the creative ecosystem by setting up foundational configuration for creative workflows and preparing the environment for intelligent automation.

```bash
# Example usage of the init command
coaia init
```

--------------------------------

### Build Docker Image for coaia-spiral

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/briefs/entity-versioning-update-operations.md

This snippet details the Dockerfile instructions for building the coaia-spiral application. It covers copying package files, installing dependencies, copying the rest of the code, building the project, and setting the command to run the server. Ensure Node.js is available in the build environment.

```dockerfile
# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install --ignore-scripts

# Copy the rest of the code
COPY . .

# Build the project
RUN npm run build

# Run the MCP server
CMD [ "node", "dist/index.js" ]
```

--------------------------------

### Install and Run COAIA Memory via NPX

Source: https://github.com/jgwill/coaia-spiral/blob/main/CLAUDE.md

This command installs and runs the COAIA Memory MCP server using npx. It specifies the path to store the memory charts. Ensure you have Node.js and npm installed. The `--memory-path` argument is mandatory.

```bash
npx coaia-spiral --memory-path ./my-charts.jsonl
```

--------------------------------

### Build and Test COAIA Memory

Source: https://github.com/jgwill/coaia-spiral/blob/main/conversations/ISSUE133.llmcon.claude.250814.txt

This section demonstrates the build process and testing of the COAIA Memory tool using npm commands. It includes building the project with 'npm run build' and testing the help functionality with '--help' and '-h' flags.

```Bash
npm run build
node dist/index.js --help
node dist/index.js -h
```

--------------------------------

### Install COAIA Memory CLI

Source: https://github.com/jgwill/coaia-spiral/blob/main/RELEASE.md

Installs and runs the COAIA Memory command-line interface, specifying a path for chart data.

```bash
npx coaia-memory --memory-path ./charts.jsonl
```

--------------------------------

### Install Minimist Type Definitions (Bash)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/workflow.md

Installs the type definitions for the 'minimist' package as a development dependency. This improves type checking and autocompletion when working with command-line arguments parsed by minimist.

```bash
volta run npm install --save-dev @types/minimist
```

--------------------------------

### Install TypeScript Globally (Bash)

Source: https://github.com/jgwill/coaia-spiral/blob/main/docs/development/workflow.md

Installs the TypeScript compiler globally using Volta, ensuring the latest version is available for use across different projects. This command is executed within the project's terminal environment.

```bash
volta install typescript
```

--------------------------------

### Initialize MCP Server with Capabilities (TypeScript)

Source: https://github.com/jgwill/coaia-spiral/blob/main/rispecs/mcp_integration.spec.md

Initializes the Model Context Protocol (MCP) server with a specified name and version, declaring its capabilities such as tool listing. This is crucial for AI assistant integration.

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Server initialization with proper capability declaration
const server = new Server(
  { name: "coaia-spiral", version: "3.0.2" },
  { capabilities: { tools: { listChanged: true } } }
);
```

--------------------------------

### CLI Usage for Storytelling Pipeline Creation

Source: https://github.com/jgwill/coaia-spiral/blob/main/__llms/llms-coaiapy-cli-guide.md

Demonstrates how to create and configure a story development pipeline using the Coaia CLI. It shows setting pipeline variables such as chain name, model, initial prompt, and enabling judge evaluation with specific criteria and models. Also includes an example for evaluating existing story content.

```bash
# Create story development pipeline with judge evaluation
coaia pipeline create llm-chain \
  --var chain_name="story_chapter_1" \
  --var model_name="claude-3" \
  --var initial_prompt="Write opening chapter of sci-fi novel" \
  --var enable_judge_evaluation=true \
  --var judge_model="gpt-4" \
  --var evaluation_criteria="creativity"

# Evaluate existing story content
coaia pipeline create judge-evaluation \
  --var content_name="chapter_draft" \
  --var content_to_evaluate="$(cat chapter1.txt)" \
  --var evaluation_criteria="narrative_quality"
```