Try It — Knowledge Graph Quick Start

Caution

This requires Docker (for Neo4j) and an OpenAI API key. If you just want to try IntentWeave, start with CARI — no dependencies needed.

1. Start Neo4j

docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/codegraph \
  neo4j:5

Verify it’s running: open http://localhost:7474 in your browser.

2. Set Environment Variables

export NEO4J_PASSWORD=codegraph
export OPENAI_API_KEY=sk-...

3. Initialize Your Workspace

cd /path/to/your/project
iw init

4. Run the Extraction Pipeline

iw run docs/*.md --track open --provider openai -i -v

What happens:

1. Documents are chunked (~16k chars/chunk)
2. OpenAI extracts entity-relationship triples per chunk
3. Entities and predicates are canonicalized
4. Cross-document entities are deduplicated

The -i flag enables incremental caching — re-runs skip unchanged files.

5. Persist to Neo4j

iw persist --latest -v

6. Query

Natural language

iw query "What are the main components?" -s my-project
iw query "What decisions were made about the database?" -s my-project -v

Raw Cypher

iw query --cypher "MATCH (n:Canon:Entity) RETURN n.name, n.type LIMIT 20"
iw query --cypher "MATCH ()-[r:CANON_REL]->() RETURN r.predicate, count(*) ORDER BY count(*) DESC"

7. Build RAG Context

# Topic-based
iw context "authentication architecture" -s my-project

# Entity-seeded (expand 3 hops from a specific entity)
iw context -e "React" --hops 3 -s my-project

8. Impact Analysis

iw impact src/auth.ts -s my-project

Traces which entities, decisions, and risks are affected by changing a file.

9. Documentation Health

# CARI mode (default — no Neo4j needed)
iw intent living

# Full KG mode (requires Neo4j)
iw intent living --neo4j -s my-project

Detects stale references, structural drift, and contradictions. The default CARI mode reads the local SQLite index; add --neo4j for the full knowledge-graph analysis.

Tips

• Use smart-mock provider for testing without API costs: --provider smart-mock
• The --from-fx flag lets you re-run only canonicalization: --from-fx <run-id>
• Output as JSON for programmatic use: -f json -o results.json
• Re-runs are fast: iw run with -i skips files whose content hasn’t changed

Programmatic API

import { runPipeline, persistToNeo4j, queryKg } from "@intentweave/cli";

// Run extraction (equivalent to iw run docs/*.md --track open --provider openai)
await runPipeline({
  paths: ["docs/"],
  track: "open",
  provider: "openai",
  incremental: true,
});

// Persist latest run to Neo4j (equivalent to iw persist --latest)
await persistToNeo4j({ latest: true, verbose: true });

// Query the knowledge graph
const answer = await queryKg({
  question: "What are the main components?",
  space: "my-project",
});
console.log(answer.text);

Next Steps

• CLI Reference — full command documentation
• Architecture Overview — how the pipeline works
• CARI Quick Start — zero-dependency local index