Documentation Index
Fetch the complete documentation index at: https://docs.cogos.natureselect.ai/llms.txt
Use this file to discover all available pages before exploring further.
Basic Setup
import asyncio
from cogos import CogOS, CogOSConfig
from cogos.prompts import default_cm_prompt, DEFAULT_CHATBOT_PROMPT
config = CogOSConfig.from_file() # auto-resolves config path
Using a Preset Template
The recommended way to get started:
cogos = (
CogOS(config)
.from_template("general")
.cm_prompt(default_cm_prompt)
.chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)
Defining Schema Manually
For custom schema structures:
from cogos import UniversalSchemaDomain
user = UniversalSchemaDomain("user_profile")
user.create_field("identity.name", "", "User's name")
user.create_field("preferences.hobbies", "", "Hobbies and interests")
cogos = (
CogOS(config)
.register(user)
.cm_prompt(default_cm_prompt)
.chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)
Build Memory
Process any text into structured memory:
asyncio.run(cogos.build("""
[user]: I'm Bob, I love hiking and sushi.
[assistant]: Great taste, Bob!
""", session_id="bob"))
Chat with Memory
Generate responses grounded in schema data:
result = asyncio.run(cogos.chat("What food do I like?", session_id="bob"))
print(result["reply"]) # "You mentioned that you love sushi!"
chat() returns a dict with the following keys:
| Key | Type | Description |
|---|
reply | str | The chatbot response |
schema_updated | bool | Whether schema auto-update was triggered this round |
context_rounds | int | Number of chat rounds included as context |
total_rounds | int | Total chat rounds in this session |
memory_injected | bool | Whether schema memory was injected (context window exceeded) |
request_data | dict | The system prompt and messages sent to the LLM |
Listen Mode
listen() provides automatic periodic memory extraction — it accumulates chat history, runs the CM agent in build mode every N turns, and recalls schema data every turn:
config = CogOSConfig.from_file()
config.build_every_n_turns = 3 # run build CM every 3 turns
cogos = (
CogOS(config)
.from_template("general")
.cm_prompt(default_cm_prompt)
.chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)
# listen() returns the chatbot reply string directly
reply = asyncio.run(cogos.listen("I'm Bob, I love hiking.", session_id="bob"))
print(reply)
chat(), listen() returns a plain string (not a dict). Build triggers when turn_number % build_every_n_turns == 0.
Selective Recall
recall() runs the CM agent in QA mode to retrieve only the schema fields relevant to a message:
result = asyncio.run(cogos.recall("What food do I like?", session_id="bob"))
print(result["recalled"]) # Formatted schema excerpt
print(result["is_selective"]) # True if the CM agent found relevant data
Dynamic Schema Update
Enable automatic schema updates during chat:
config = CogOSConfig.from_file()
config.schema_update_rounds = 5 # update schema every 5 chat rounds
cogos = (
CogOS(config)
.from_template("general")
.cm_prompt(default_cm_prompt)
.chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)
# chat() returns a dict with reply and schema_updated flag
result = asyncio.run(cogos.chat("I just got promoted to Senior Engineer!", session_id="bob"))
print(result["reply"]) # The chatbot response
print(result["schema_updated"]) # True if schema was auto-updated this round
# Manual trigger: update schema from last 10 rounds of chat
asyncio.run(cogos.update_schema_from_chat(session_id="bob", rounds=10))
.use() and custom SCP tools via .tools():
cogos = (
CogOS(config)
.from_template("general")
.cm_prompt(default_cm_prompt)
.chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
.use(MyRAGPlugin("http://localhost:9000")) # add plugin hooks
.tools(my_custom_tools_builder) # add custom SCP tools
)
Config Loading
Multiple ways to load configuration:
from cogos import CogOSConfig
config = CogOSConfig.from_file() # auto-resolve + env vars
config = CogOSConfig.from_file("configs/cogos.yaml") # explicit path
config = CogOSConfig.from_env() # env vars only
config = CogOSConfig(model="gpt-5.4") # direct construction
Custom CM Prompt
Override the default CM agent behavior:
def my_cm_prompt(state, registry):
schema_overview = registry.inspect_all(max_depth=3)
return f"""You are a medical records agent.
Available schemas:
{schema_overview}
Extract: diagnoses, medications, allergies, vitals.
When done: {{"continue": false}}"""
cogos = CogOS(config).cm_prompt(my_cm_prompt).chatbot_prompt(my_template)
