crabpath（crabpath 搜索）

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/