npcsh 1.1.17__tar.gz → 1.1.19__tar.gz

{npcsh-1.1.17/npcsh.egg-info → npcsh-1.1.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: npcsh
-Version: 1.1.17
+Version: 1.1.19
 Summary: npcsh is a command-line toolkit for using AI agents in novel ways.
 Home-page: https://github.com/NPC-Worldwide/npcsh
 Author: Christopher Agostino
@@ -106,31 +106,38 @@ Dynamic: summary
   <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/npcsh/npcsh.png" alt="npcsh logo" width=600></a>
 </p> 
 
-# NPC Shell
+# npcsh
 
-`npcsh` - a new standard in human-agent interaction. Co-create with agents to build organizations that refine themselves and evolve to your needs.
-
-The NPC shell is a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. Based in the command line, use it wherever you work. 
-
-- It is developed to work reliably with small models and performs excellently with the state-of-the-art models from major model providers. 
-- Fundamentally, the core program of npcsh extends the familiar bash environment with an intelligent layer that lets users seamlessly ask agents questions, run pre-built or custom macros or agents, all without breaking the flow of command-line work.
-- Switching between agents is a breeze in `npcsh`, letting you quickly and easily take advantage of a variety of agents (e.g. coding agents versus tool-calling agents versus prompt-based ReACT Flow agents) and personas (e.g. Data scientist, mapmaker with ennui, etc.).
-- Project variables and context can be stored in team `.ctx` files. Personas (`.npc`) and Jinja execution templates (`.jinx`) are likewise stored in `yaml` within the global `npcsh` team or your project-specific one, letting you focus on adjusting and engineering context and system prompts iteratively so you can constantly improve your agent team's performance.
+The NPC shell (`npcsh`) makes the most of multi-modal LLMs and agents through a powerful set of simple slash  commands and novel interactive modes, all from the comfort of the command line. Build teams of agents and schedule them on jobs, engineer context, and design custom interaction modes and Jinja Execution templates (Jinxs for you and your agents to invoke, all managed scalably for organizations of any size through the NPC data layer.
 
 To get started:
+For users who want to mainly use models through APIs (`ollama`, `gemini`, `kimi`, `grok`, `deepseek`, `anthropic`, `openai`, `mistral`, or any others provided by litellm )
 ```bash
-# for users who want to mainly use models through APIs (e.g. , gemini, grok, deepseek, anthropic, openai, mistral, , any others provided by litellm ):
 pip install 'npcsh[lite]' 
-# for users who want to use local models (these install diffusers/transformers/torch stack so it is big.):
+```
+For users who want to use and fine-tune local models (this installs `diffusers`/`transformers`/`torch` stack so it is big):
+
+```bash
 pip install 'npcsh[local]'
-# for users who want to use the voice mode `yap`, see also the OS-specific installation instructions for installing needed system audio  libraries
+```
+
+
+For users who want to use the voice mode `yap` (see also the OS-specific installation instructions for installing needed system audio  libraries)
+```bash
 pip install 'npcsh[yap]'
 ```
+
 Once installed: run
 ```bash
 npcsh
 ```
-and you will enter the NPC shell. Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
+and you will enter the NPC shell. 
+
+If you do not have any local models
+
+
+
+Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
 
 
 # Usage
@@ -596,6 +603,9 @@ npc vixynt "a sunset over mountains"
 | `/teamviz` | Visualize team structure. Usage: `/teamviz save=output.png` |
 | `/ots` | Screenshot analysis. Usage: `/ots` then select area |
 | `/sleep` | Evolve knowledge graph. Usage: `/sleep --ops link_facts,deepen` |
+| `/kg_search` | Search knowledge graph with multiple modes. Usage: `/kg_search query mode=hybrid depth=2` |
+| `/mem_search` | Search approved memories. Usage: `/mem_search query status=approved top_k=10` |
+| `/mem_review` | Review pending memories interactively. Usage: `/mem_review limit=50` |
 
 ### System & Config
 | Command | Description |
@@ -626,6 +636,92 @@ npc vixynt "a sunset over mountains"
     --format          (-f)         | --num_frames      (-num_f)     | --sprovider       (-s)         |                               
     ```
 
+## Memory & Knowledge Graph
+
+`npcsh` maintains a memory lifecycle system that allows agents to learn and grow from past interactions. Memories progress through stages and can be incorporated into a knowledge graph for advanced retrieval.
+
+### Memory Lifecycle
+
+Memories are extracted from conversations and follow this lifecycle:
+
+1. **pending_approval** - New memories awaiting review
+2. **human-approved** - Approved and ready for KG integration
+3. **human-rejected** - Rejected (used as negative examples)
+4. **human-edited** - Modified by user before approval
+5. **skipped** - Deferred for later review
+
+### Memory Commands
+
+```bash
+# Search through approved memories
+/mem_search python                      # Keyword search
+/mem_search python status=approved      # Filter by status
+/mem_search python top_k=20             # Limit results
+
+# Review pending memories interactively
+/mem_review                             # Review with default limit
+/mem_review limit=50                    # Review more at once
+```
+
+### Knowledge Graph
+
+The knowledge graph stores facts and concepts extracted from approved memories, enabling semantic search and reasoning. Facts are linked to concepts, allowing traversal-based discovery.
+
+```bash
+# Keyword search
+/kg_search python                       # Simple keyword match
+
+# Semantic similarity search
+/kg_search python mode=embedding        # Find semantically similar facts
+
+# Graph traversal search
+/kg_search python mode=link depth=3     # Traverse graph links
+
+# Hybrid search (combines methods)
+/kg_search python mode=all              # All methods combined
+
+# Explore concepts
+/kg_search type=concepts                # List all concepts
+/kg_search concept="Machine Learning"   # Explore a specific concept
+```
+
+### Knowledge Graph Evolution
+
+The `/sleep` command evolves the knowledge graph through consolidation, abstraction, and creative synthesis:
+
+```bash
+# Basic sleep (consolidation)
+/sleep
+
+# Import approved memories first, then evolve
+/sleep backfill=true
+
+# Dream mode - creative synthesis across domains
+/sleep dream=true
+
+# Combined backfill and dream
+/sleep backfill=true dream=true
+
+# Specific operations
+/sleep ops=prune,deepen,abstract
+```
+
+**Operations:**
+- **prune** - Remove redundant or low-value facts
+- **deepen** - Add detail to existing facts
+- **abstract** - Create higher-level generalizations
+- **link** - Connect related facts and concepts
+
+### Environment Variables
+
+```bash
+# Enable/disable automatic KG building (default: enabled)
+export NPCSH_BUILD_KG=1
+
+# Database path
+export NPCSH_DB_PATH=~/npcsh_history.db
+```
+
 ## Read the Docs
 To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)
 

{npcsh-1.1.17 → npcsh-1.1.19}/README.md

@@ -3,31 +3,38 @@
   <img src="https://raw.githubusercontent.com/NPC-Worldwide/npcsh/main/npcsh/npcsh.png" alt="npcsh logo" width=600></a>
 </p> 
 
-# NPC Shell
+# npcsh
 
-`npcsh` - a new standard in human-agent interaction. Co-create with agents to build organizations that refine themselves and evolve to your needs.
-
-The NPC shell is a suite of programs to make use of multi-modal LLMs and agents in novel interactive modes. Based in the command line, use it wherever you work. 
-
-- It is developed to work reliably with small models and performs excellently with the state-of-the-art models from major model providers. 
-- Fundamentally, the core program of npcsh extends the familiar bash environment with an intelligent layer that lets users seamlessly ask agents questions, run pre-built or custom macros or agents, all without breaking the flow of command-line work.
-- Switching between agents is a breeze in `npcsh`, letting you quickly and easily take advantage of a variety of agents (e.g. coding agents versus tool-calling agents versus prompt-based ReACT Flow agents) and personas (e.g. Data scientist, mapmaker with ennui, etc.).
-- Project variables and context can be stored in team `.ctx` files. Personas (`.npc`) and Jinja execution templates (`.jinx`) are likewise stored in `yaml` within the global `npcsh` team or your project-specific one, letting you focus on adjusting and engineering context and system prompts iteratively so you can constantly improve your agent team's performance.
+The NPC shell (`npcsh`) makes the most of multi-modal LLMs and agents through a powerful set of simple slash  commands and novel interactive modes, all from the comfort of the command line. Build teams of agents and schedule them on jobs, engineer context, and design custom interaction modes and Jinja Execution templates (Jinxs for you and your agents to invoke, all managed scalably for organizations of any size through the NPC data layer.
 
 To get started:
+For users who want to mainly use models through APIs (`ollama`, `gemini`, `kimi`, `grok`, `deepseek`, `anthropic`, `openai`, `mistral`, or any others provided by litellm )
 ```bash
-# for users who want to mainly use models through APIs (e.g. , gemini, grok, deepseek, anthropic, openai, mistral, , any others provided by litellm ):
 pip install 'npcsh[lite]' 
-# for users who want to use local models (these install diffusers/transformers/torch stack so it is big.):
+```
+For users who want to use and fine-tune local models (this installs `diffusers`/`transformers`/`torch` stack so it is big):
+
+```bash
 pip install 'npcsh[local]'
-# for users who want to use the voice mode `yap`, see also the OS-specific installation instructions for installing needed system audio  libraries
+```
+
+
+For users who want to use the voice mode `yap` (see also the OS-specific installation instructions for installing needed system audio  libraries)
+```bash
 pip install 'npcsh[yap]'
 ```
+
 Once installed: run
 ```bash
 npcsh
 ```
-and you will enter the NPC shell. Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
+and you will enter the NPC shell. 
+
+If you do not have any local models
+
+
+
+Additionally, the pip installation includes the following CLI tools available in bash: `npc` cli, `wander`, `spool`, `yap`, and `nql`. Bin jinxs in `npc_team/jinxs/bin/` are automatically registered as CLI commands. 
 
 
 # Usage
@@ -493,6 +500,9 @@ npc vixynt "a sunset over mountains"
 | `/teamviz` | Visualize team structure. Usage: `/teamviz save=output.png` |
 | `/ots` | Screenshot analysis. Usage: `/ots` then select area |
 | `/sleep` | Evolve knowledge graph. Usage: `/sleep --ops link_facts,deepen` |
+| `/kg_search` | Search knowledge graph with multiple modes. Usage: `/kg_search query mode=hybrid depth=2` |
+| `/mem_search` | Search approved memories. Usage: `/mem_search query status=approved top_k=10` |
+| `/mem_review` | Review pending memories interactively. Usage: `/mem_review limit=50` |
 
 ### System & Config
 | Command | Description |
@@ -523,6 +533,92 @@ npc vixynt "a sunset over mountains"
     --format          (-f)         | --num_frames      (-num_f)     | --sprovider       (-s)         |                               
     ```
 
+## Memory & Knowledge Graph
+
+`npcsh` maintains a memory lifecycle system that allows agents to learn and grow from past interactions. Memories progress through stages and can be incorporated into a knowledge graph for advanced retrieval.
+
+### Memory Lifecycle
+
+Memories are extracted from conversations and follow this lifecycle:
+
+1. **pending_approval** - New memories awaiting review
+2. **human-approved** - Approved and ready for KG integration
+3. **human-rejected** - Rejected (used as negative examples)
+4. **human-edited** - Modified by user before approval
+5. **skipped** - Deferred for later review
+
+### Memory Commands
+
+```bash
+# Search through approved memories
+/mem_search python                      # Keyword search
+/mem_search python status=approved      # Filter by status
+/mem_search python top_k=20             # Limit results
+
+# Review pending memories interactively
+/mem_review                             # Review with default limit
+/mem_review limit=50                    # Review more at once
+```
+
+### Knowledge Graph
+
+The knowledge graph stores facts and concepts extracted from approved memories, enabling semantic search and reasoning. Facts are linked to concepts, allowing traversal-based discovery.
+
+```bash
+# Keyword search
+/kg_search python                       # Simple keyword match
+
+# Semantic similarity search
+/kg_search python mode=embedding        # Find semantically similar facts
+
+# Graph traversal search
+/kg_search python mode=link depth=3     # Traverse graph links
+
+# Hybrid search (combines methods)
+/kg_search python mode=all              # All methods combined
+
+# Explore concepts
+/kg_search type=concepts                # List all concepts
+/kg_search concept="Machine Learning"   # Explore a specific concept
+```
+
+### Knowledge Graph Evolution
+
+The `/sleep` command evolves the knowledge graph through consolidation, abstraction, and creative synthesis:
+
+```bash
+# Basic sleep (consolidation)
+/sleep
+
+# Import approved memories first, then evolve
+/sleep backfill=true
+
+# Dream mode - creative synthesis across domains
+/sleep dream=true
+
+# Combined backfill and dream
+/sleep backfill=true dream=true
+
+# Specific operations
+/sleep ops=prune,deepen,abstract
+```
+
+**Operations:**
+- **prune** - Remove redundant or low-value facts
+- **deepen** - Add detail to existing facts
+- **abstract** - Create higher-level generalizations
+- **link** - Connect related facts and concepts
+
+### Environment Variables
+
+```bash
+# Enable/disable automatic KG building (default: enabled)
+export NPCSH_BUILD_KG=1
+
+# Database path
+export NPCSH_DB_PATH=~/npcsh_history.db
+```
+
 ## Read the Docs
 To see more about how to use the jinxs and modes in the NPC Shell, read the docs at [npc-shell.readthedocs.io](https://npc-shell.readthedocs.io/en/latest/)