CrabPath

Pure graph core: zero required deps and no network calls. Caller provides callbacks.

Design Tenets

• No network calls in core
• No secret discovery (no dotfiles, keychain, or env probing)
• No subprocess provider wrappers
• Embedder identity in state metadata; dimension mismatches are errors
• One canonical state format (state.json)

Quick Start

from crabpath import split_workspace, HashEmbedder, VectorIndex

graph, texts = split_workspace("./workspace")
embedder = HashEmbedder()
index = VectorIndex()
for nid, content in texts.items():
    index.upsert(nid, embedder.embed(content))

Embeddings and LLM callbacks

• Default: HashEmbedder (hash-v1, 1024-dim)
• Real: callback embed_fn / embed_batch_fn (e.g., text-embedding-3-small)
• LLM routing: callback llm_fn using gpt-5-mini (example)

Session Replay

replay_queries(graph, queries) can warm-start from historical turns.

CLI

--state is preferred:

crabpath query TEXT --state S [--top N] [--json]

crabpath query TEXT --state S --chat-id CID

crabpath doctor --state S

crabpath info --state S

crabpath init --workspace W --output O --embedder openai

crabpath query TEXT --state S --llm openai

crabpath inject --state S --type TEACHING [--type DIRECTIVE]

Real-time correction flow:

python3 query_brain.py --chat-id CHAT_ID

python3 learn_correction.py --chat-id CHAT_ID

Quick Reference

• crabpath init/query/learn/inject/health/doctor/info
• query_brain.py --chat-id and learn_correction.py for real-time correction pipelines
• query_brain.py traversal limits: beam_width=8, max_hops=30, fire_threshold=0.01
• Hard traversal caps: max_fired_nodes and max_context_chars (defaults None; query_brain.py defaults max_context_chars=20000)
• examples/correction_flow/, examples/cold_start/, examples/openai_embedder/

API Reference

• Core lifecycle:
• split_workspace
• load_state
• save_state
• ManagedState
• VectorIndex
• Traversal and learning:
• traverse
• TraversalConfig
• TraversalConfig.beam_width, .max_hops, .fire_threshold, .max_fired_nodes, .max_context_chars, .reflex_threshold, .habitual_range, .inhibitory_threshold
• TraversalResult
• apply_outcome
• Runtime injection APIs:
• inject_node
• inject_correction
• inject_batch
• Maintenance helpers:
• suggest_connections, apply_connections
• suggest_merges, apply_merge
• measure_health, autotune, replay_queries
• Embedding utilities:
• HashEmbedder
• OpenAIEmbedder
• default_embed
• default_embed_batch
• openai_llm_fn
• LLM routing callbacks:
• chat_completion
• Graph primitives:
• Node
• Edge
• Graph
• split_workspace
• generate_summaries

CLI Commands

• crabpath init --workspace W --output O [--sessions S] [--embedder openai]
• crabpath query TEXT --state S [--top N] [--json] [--chat-id CHAT_ID]
• crabpath learn --state S --outcome N --fired-ids a,b,c [--json]
• crabpath inject --state S --id NODE_ID --content TEXT [--type CORRECTION|TEACHING|DIRECTIVE] [--json] [--connect-min-sim 0.0]
• crabpath inject --state S --id NODE_ID --content TEXT --type TEACHING
• crabpath inject --state S --id NODE_ID --content TEXT --type DIRECTIVE
• crabpath health --state S
• crabpath doctor --state S
• crabpath info --state S
• crabpath replay --state S --sessions S
• crabpath merge --state S [--llm openai]
• crabpath connect --state S [--llm openai]
• crabpath journal [--stats]
• query_brain.py --chat-id CHAT_ID
• learn_correction.py --chat-id CHAT_ID

Traversal defaults

• beam_width=8
• max_hops=30
• fire_threshold=0.01
• reflex_threshold=0.6
• habitual_range=0.2-0.6
• inhibitory_threshold=-0.01
• max_fired_nodes (hard node-count cap, default None)
• max_context_chars (hard context cap, default None; query_brain.py default is 20000)

Paper

https://jonathangu.com/crabpath/