Merge branch 'main' of github.com:tinyhumansai/neocortex

Author: senamakel

.github/workflows/publish-python-sdk.yml

@@ -13,6 +13,9 @@ jobs:
     environment: Production
     permissions:
       id-token: write
+    defaults:
+      run:
+        working-directory: packages/sdk-python
     steps:
       - uses: actions/checkout@v4
 
@@ -25,6 +28,7 @@ jobs:
         run: uv build
 
       - name: Publish to PyPI
+        working-directory: packages/sdk-python
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}

packages/plugin-agno/README.md

@@ -0,0 +1,81 @@
+# Neocortex Agno Plugin
+
+Agno plugin for **Neocortex-powered memories** in Agno agents. Gives your agents persistent memory (save, recall, delete) via the Neocortex/TinyHumans API, with credentials kept out of tool parameters.
+
+## Requirements
+
+- Python 3.9+
+- [Agno](https://pypi.org/project/agno/) ≥ 2.0
+- [httpx](https://www.python-httpx.org/) (brought in as a dependency) for talking to the Alphahuman backend.
+
+## Install
+
+```bash
+pip install neocortex-agno
+```
+
+Or from the repo:
+
+```bash
+pip install -e ./neocortex/packages/plugin-agno
+```
+
+## Quick start
+
+```python
+from agno.agent import Agent
+from agno.models.openai import OpenAIResponses
+from neocortex_agno import NeocortexTools
+
+agent = Agent(
+    model=OpenAIResponses(id="gpt-4o-mini"),
+    tools=[NeocortexTools(token="YOUR_ALPHAHUMAN_API_KEY")],
+    instructions="Use the memory tools to remember and recall user preferences and context.",
+    markdown=True,
+)
+
+# Agent can now save and recall memories
+agent.print_response("Remember that I prefer dark mode and my name is Alex.", stream=True)
+agent.print_response("What theme do I prefer?", stream=True)
+```
+
+## Available tools
+
+The `NeocortexTools` toolkit exposes three tools to the agent:
+
+
+| Tool            | Description                                                           |
+| --------------- | --------------------------------------------------------------------- |
+| `save_memory`   | Save or update a memory (key, content, namespace, optional metadata). |
+| `recall_memory` | Recall relevant memories for a natural-language query in a namespace. |
+| `delete_memory` | Delete one or more memories by key/keys or delete all in a namespace. |
+
+
+Credentials (`token`, `model_id`, `base_url`) are set when constructing `NeocortexTools` and are **never** passed as tool arguments, so the LLM cannot see or override them.
+
+## Configuration
+
+- **token** (required): Alphahuman / Neocortex memory API token (e.g. `ALPHAHUMAN_API_KEY`).
+- **base_url** (optional): Alphahuman API base URL. If omitted, uses the `ALPHAHUMAN_BASE_URL` env var or the default `https://staging-api.alphahuman.xyz`.
+
+## Error handling
+
+On API failures, the underlying client raises `TinyHumanError`. You can catch it for logging or user-facing messages:
+
+```python
+from neocortex_agno import NeocortexTools, AlphahumanError
+
+try:
+    agent.print_response("Remember that I like Python.", stream=True)
+except AlphahumanError as e:
+    print(f"Memory API error: {e} (status={e.status})")
+```
+
+## Example
+
+An example script is included. Set `ALPHAHUMAN_API_KEY`, `ALPHAHUMAN_BASE_URL`, and `OPENAI_API_KEY`, then:
+
+```bash
+python example.py
+```
+

packages/plugin-agno/example.py

@@ -0,0 +1,52 @@
+"""Example: Agno agent with Neocortex (Alphahuman) memory tools.
+
+Run with:
+  export ALPHAHUMAN_API_KEY=""
+  export ALPHAHUMAN_BASE_URL=""
+  export OPENAI_API_KEY=""
+  python example.py
+"""
+
+import os
+
+from agno.agent import Agent
+from agno.models.openai import OpenAIResponses
+from neocortex_agno import NeocortexTools
+
+
+def main() -> None:
+    token = os.environ.get("ALPHAHUMAN_API_KEY")
+    if not token:
+        print("Set ALPHAHUMAN_API_KEY to run this example.")
+        return
+
+    agent = Agent(
+        model=OpenAIResponses(id="gpt-4o-mini"),
+        tools=[
+            NeocortexTools(
+                token=token,
+                base_url=os.environ.get("ALPHAHUMAN_BASE_URL"),
+            )
+        ],
+        instructions=(
+            "Use the memory tools to remember and recall user preferences and context. "
+            "When the user tells you something to remember, use save_memory. "
+            "When answering questions that might use stored context, use recall_memory first."
+        ),
+        markdown=True,
+    )
+
+    print("Agent with Neocortex memory ready. Try:")
+    print('  agent.print_response("Remember that I prefer dark mode.", stream=True)')
+    print('  agent.print_response("What theme do I prefer?", stream=True)')
+    print()
+
+    agent.print_response(
+        "Remember that I prefer dark mode and my name is Alex.",
+        stream=True,
+    )
+    agent.print_response("What theme do I prefer?", stream=True)
+
+
+if __name__ == "__main__":
+    main()

packages/plugin-agno/neocortex_agno/__init__.py

@@ -0,0 +1,6 @@
+"""Neocortex plugin for Agno — Neocortex-powered memories in Agno agents."""
+
+from .tools import NeocortexTools, AlphahumanError
+
+__all__ = ["NeocortexTools", "AlphahumanError"]
+__version__ = "0.1.0"