NPC-Worldwide/npcpy

---

name: create_jinx

description: Write a new .jinx file from inputs (name, description, inputs spec as JSON list of strings, python body). Agents use this mid-task to crystallize a repeated block of code into a reusable jinx. The jinx is written to the team's jinxes/lib dir by default and registered with the running team so it is immediately callable without a restart.

---

name: knowledge_graph_skill

description: Skill for searching and evolving the SQLite-backed Knowledge Graph. Use this when you need structured fact/concept/link search across one or more teams, NPCs, or directory scopes. The Knowledge Graph (KG) is stored in the application's database (not YAML). It is scoped by (team_name, npc_name, directory_path). Facts and concepts carry generation numbers and origin tags. Search methods (choose the right one): 1. Keyword search — fast substring match over fact statements. `kg_search_facts(engine_or_kg, "keyword")` → List[str] 2. Embedding search — semantic cosine similarity via vector embeddings. `kg_embedding_search(engine_or_kg, query="...", embedding_model="nomic-embed-text", embedding_provider="ollama", similarity_threshold=0.6, max_results=20)` → List[dict] with 'content', 'type', 'score' 3. Link search — graph traversal (BFS/DFS) starting from keyword-matched seeds. `kg_link_search(engine_or_kg, query="...", max_depth=2, breadth_per_step=5, strategy="bfs", max_results=20)` → List[dict] with 'content', 'type', 'depth', 'path', 'score' 4. Hybrid search — combines keyword + embedding + link, boosting results found by multiple methods. `kg_hybrid_search(engine_or_kg, query="...", mode="all", max_depth=2, similarity_threshold=0.6, max_results=20)` → List[dict] with 'content', 'type', 'score', 'source' Graph evolution (use sparingly, usually in background): - `kg_initial(content, model, provider)` — build a new KG from text - `kg_evolve_incremental(existing_kg, new_content_text, ...)` — add content - `kg_sleep_process(existing_kg, model, provider)` — prune/deepen/consolidate - `kg_dream_process(existing_kg, model, provider, num_seeds)` — speculative synthesis When a user asks a question that spans facts, concepts, and their relationships, prefer hybrid search. For pure semantic similarity without graph structure, use embedding search. For exploring connected neighborhoods, use link search with BFS.

---

name: knowledge_index_skill

description: Skill for using the KnowledgeIndex registry to discover which directories contain `.knowledge.yaml` files without walking the filesystem. KnowledgeIndex is a lightweight SQLite cache. It maps directory paths to file metadata (mtime, memory_count, link_count). The database path is caller-provided — npcpy does not hardcode a default. Key operations: - Upsert a directory after writing to its YAML: `upsert_directory(db_path, directory, memory_count, link_count)` - List known directories: `get_known_directories(db_path, min_mtime=None)` - Full rescan of a tree: `scan_root(db_path, root, max_depth=5)` - Remove a stale directory: `remove_directory(db_path, directory)` Typical flow: 1. Call `scan_root(db_path, root="/home/user/projects", max_depth=5)` to populate the index with every `.knowledge.yaml` found. 2. Query `get_known_directories(db_path)` to get a list of directories with memory/link counts. 3. For each directory of interest, instantiate `KnowledgeStore(directory)` and call `load()` or `build_context()`. The index is a cache, not the source of truth. If a `.knowledge.yaml` is deleted or modified outside the app, re-run `scan_root` to refresh.

---

name: knowledge_sememolution_skill

description: Skill for population-based Knowledge Graph evolution via Sememolution. Use this when the user wants creative cross-domain synthesis, speculative reasoning, or when a single KG search might be too narrow. Sememolution maintains a population of KG "individuals". Each individual has its own graph (different facts, concepts, links) and its own genome controlling how it searches and evolves. Core genome parameters: - `lambda_depth` — Poisson rate for search traversal depth - `lambda_breadth` — Poisson rate for search breadth per step - `sleep_ops` — which refinement ops to apply during sleep - `dream_probability` — chance of speculative synthesis per cycle Workflow: 1. Create a population: `SememolutionPopulation(model, provider, population_size=100, sample_size=10)` 2. Initialize: `pop.initialize()` 3. Assimilate text: `pop.assimilate_text(chunk)` — each individual absorbs it differently 4. Sleep cycle: `pop.sleep_cycle()` — each individual prunes/deepens independently 5. Query and rank: `pop.query_and_rank(question)` — sample individuals, each searches its own graph with Poisson-sampled depth/breadth, generates a response, and responses are ranked. Winners get fitness bumps. 6. Evolve: `pop.evolve_generation()` — tournament selection, crossover, mutation. When to use this: - The user asks open-ended "what if" or "how might X relate to Y" questions - You need diverse perspectives on the same knowledge corpus - You want to discover non-obvious connections across domains - Standard KG search returns shallow or overly literal results Important: this is computationally expensive. Only invoke after checking whether standard keyword/embedding/hybrid search is sufficient.

---

name: knowledge_store_skill

description: Skill for working with local .knowledge.yaml files via KnowledgeStore. Use this when you need to recall, search, or manage directory-local memories and knowledge links stored in plain YAML alongside the user's project files. KnowledgeStore is directory-scoped. Each directory that contains a `.knowledge.yaml` file maintains its own append-only memory graph. There is no global database — the YAML IS the source of truth. Key operations: - Load a directory's store: `npcpy.memory.knowledge_store.get_store_for_path(path)` - Append a memory: `store.append_memory(initial_memory="...", status="pending_approval", ...)` - Update a memory (approve/reject/edit): `store.update_memory(mem_id, status, final_memory)` - Search memories (keyword substring): `store.search_memories("query", limit=20)` - Get approved context for LLM prompts: `store.build_context(max_memories=10)` - Get links for a memory: `store.get_links_for_memory(mem_id)` - Create a link between memories: `store.append_link(from_mem, to_mem, relation="refines", agent="your_name")` - Aggregate across a tree: `KnowledgeStore.aggregate(root_directory, max_depth=3)` Memory statuses: - `pending_approval` — raw extraction, needs human review - `human-approved` — confirmed and available for context injection - `human-rejected` — discard, can be used as negative examples - `human-edited` — corrected version supersedes initial_memory When answering questions, prefer `build_context()` for recently approved local knowledge, and `search_memories()` for targeted recall. Always respect `human-rejected` memories — do not repeat them.

---

name: natural

description: Render the provided prompt template with Jinja context and send it to the active NPC's LLM. The rendered text becomes the user prompt; the LLM response is placed in context['output'].

---

name: run_jinx

description: Execute a jinx by name (already loaded on the team) or by filesystem path (e.g. a freshly created_jinx that isn't yet registered), passing input values as a JSON object. Returns the jinx's output field or the full context dict. Use this to run a jinx you just wrote without exiting the session.