CrabPath

Memory graph engine with caller-provided embed and LLM callbacks; core is pure, with real-time correction flow and optional OpenAI integration.

Security Scan

The package appears to be what it claims: a local, pure-Python memory-graph engine with optional, explicitly opt-in OpenAI integration — no unexplained credential requests or hidden installers were found.

Purpose & Capability

Name/description (memory graph with optional LLM/embed callbacks) matches the repository contents: core graph code, CLI, daemon, example adapters, and optional OpenAI helper files. The repo separates core (zero-deps hash embedder, VectorIndex, traversal) from optional OpenAI integration (openai_embeddings.py, openai_llm.py and benchmark/example scripts). No required env vars or binaries are declared, which aligns with the 'zero required deps' claim.

Instruction Scope

SKILL.md and README explicitly state core makes no network calls and that callers supply embed/LLM callbacks. The examples and benchmark scripts do perform network calls when run with the OpenAI client (they require an OpenAI client / API key if you choose that path). This is documented and opt-in; however, many example and benchmark files will perform network calls if executed, so users should be conscious about running those scripts.

Install Mechanism

No install spec is included in the skill metadata (instruction-only skill). The repository contains source files but there is no remote download/install URL or package-fetching step in the skill metadata. That is low-risk from an install mechanism perspective.

Credentials

The skill declares no required environment variables or credentials (primaryEnv none). OpenAI integration and some benchmarks expect an OpenAI client / OPENAI_API_KEY if you choose to run them, but that is optional and appears to be clearly documented in README/benchmarks. No evidence of implicit secret discovery (dotfile/keychain probing) is present in the SKILL.md; the codebase follows an explicit opt-in pattern for API usage in examples/benchmarks.

Persistence & Privilege

always:false and disable-model-invocation:false (normal). The package provides a daemon mode that keeps state in memory and exposes a JSON-RPC (NDJSON) protocol over stdin/stdout; this is a documented runtime mode and not secretly forced on agents. The daemon's behavior and state paths are explicit in docs (e.g., ~/.crabpath/main/state.json).

Assessment

This skill is internally coherent: the core is local and dependency-free, while OpenAI usage is optional and present only in helper modules and example/benchmark scripts. Before installing or running anything: 1) if you do not want any network activity, avoid running the examples/benchmarks or passing the --embedder/--llm flags that enable OpenAI; 2) if you enable OpenAI, only provide an API key to the runtime you control and inspect openai_* example code to ensure it uses the key only where you expect; 3) the daemon runs a JSON-RPC over stdin/stdout — treat it like any long-lived process that will load a state.json from a filesystem path you choose; 4) if you plan to run benchmarks or the daemon in production, run tests locally in an isolated environment and review state/save paths to avoid storing sensitive data in shared locations.

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/