wisemonkey 2026.6.16__tar.gz

wisemonkey-2026.6.16/.env.example

@@ -0,0 +1,3 @@
+# Copy this file to .env and fill in your key.
+# The openai package will read OPENAI_API_KEY automatically.
+OPENAI_API_KEY=

wisemonkey-2026.6.16/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# dotenv
+.env
+
+# Virtual environments
+.venv
+
+# Hermes agent
+.hermes

wisemonkey-2026.6.16/.python-version

@@ -0,0 +1 @@
+3.13

wisemonkey-2026.6.16/AGENTS.md

@@ -0,0 +1,160 @@
+# Wisemonkey — Project Guide
+
+## What is this project?
+
+Wisemonkey is a simple, extensible CLI AI agent for Linux and macOS terminals. It connects to any OpenAI/Anthropic/Ollama-compatible endpoint and provides session management, persistent memory, vector store document embedding, native + MCP tools, and skills.
+
+## Project Structure
+
+```
+wisemonkey/
+├── agent/                  # Core agent code.
+│   ├── agent.py            # Main agent loop, prompt handling, key bindings.
+│   ├── commands.py         # Slash commands (e.g. /embed, /quit).
+│   ├── config.py           # Configuration loading and handling.
+│   ├── console.py          # Rich console output with themed formatting.
+│   ├── core.py             # Core agent functions, like API connection and tool calls.
+│   ├── mcp.py              # MCP server support.
+│   ├── memory.py           # Session memory, paste file creation.
+│   ├── router.py           # API router implementation for OpenAI, Ollama, and Anthropic.
+│   ├── skills.py           # Skill loading and management.
+│   ├── tools.py            # Tool definitions.
+│   ├── update.py           # Update management.
+│   ├── utils.py            # Utility functions.
+│   └── vectorstore.py      # Vector store wrapper.
+├── tools/                  # Tool implementations available to the model.
+│   ├── basic.py            # Basic and example tools.
+│   ├── files.py            # File read/write tools.
+│   ├── memory.py            # search_knowledge tool.
+│   ├── network.py          # URL fetching.
+│   ├── terminal.py         # Shell command execution.
+│   └── vectorstore.py      # Vector store tool handler.
+├── skills/                 # Skill definitions. Add new skills here.
+│   ├── example.md
+│   └── rolldice.md
+├── tests/                  # Contains all `unittest` tests.
+│   └── [...]
+├── config.yaml             # Default config file.
+├── README.md
+├── pyproject.toml
+├── install.sh              # Installer script.
+└── .env.example
+```
+
+## Key Architectural Patterns
+
+### System Prompt Construction (`agent/core.py`)
+
+The system prompt is built in `Core._build_system_prompt()` each turn. It assembles, in order:
+1. Base system prompt from config
+2. `AGENTS.md` workspace instructions (if found)
+3. Formatted memory (user profile, notes)
+4. Chat history
+5. Loaded skills
+
+### Tool System (`agent/tools.py` + `tools/`)
+
+Tools are defined using the `@tool(name, description, parameters)` decorator. They are auto-discovered on startup. Each tool file in `tools/` contains one or more decorated handler functions.
+
+### Slash Commands (`agent/commands.py`)
+
+Commands use the `@cmd(name, description, aliases)` decorator and are auto-registered. Each returns `(ok: bool, msg: str, content: str, markdown: str)`.
+
+### Skills (`agent/skills.py` + `skills/`)
+
+Skills are `.md` files with YAML frontmatter (`name`, `description`). The body is injected into the system prompt. Follows the agentskills.io standard.
+
+### Memory (`agent/memory.py`)
+
+- **User profile** (`user_profile.json`) — set via `set_user_profile` tool
+- **Notes** (`notes.json`) — added via `save_note` tool
+- **Chat history** (`chat_history.json`) — rolling window of recent exchanges
+- All stored per-session under `~/.local/share/wisemonkey/sessions/$SESSION_NAME/`
+
+### Sessions
+
+Sessions are directories under `~/.local/share/wisemonkey/sessions/`. Each session has its own memory, chat history, and vector store. Session name defaults to `default`.
+
+## How to Extend
+
+### Adding a Tool
+
+1. Create or edit a file in `tools/`
+2. Decorate a function with `@tool(name, description, parameters)`
+3. The tool is auto-discovered — no registration needed
+
+### Adding a Slash Command
+
+1. Add a function in `agent/commands.py`
+2. Decorate with `@cmd(name, description, aliases=[])`
+3. Return `(ok, msg, content, markdown)`
+
+### Adding a Skill
+
+1. Create a `.md` file in `skills/` with YAML frontmatter (`name`, `description`)
+2. The skill body is injected into the system prompt automatically
+
+## Configuration
+
+Configuration lives in `$XDG_CONFIG_HOME/wisemonkey/config.yaml` (created on first run). Key sections:
+- `model` — provider, name, base_url, temperature, reasoning
+- `embedding` — embedding model name and endpoint
+- `agent` — max_turns, system_prompt, max_chat_history, vi_mode
+
+Run `wisemonkey --onboard` for interactive configuration.
+
+## Development
+
+- Requires Python 3.13+ and `uv`
+- Dependencies: `uv sync`
+- Run from source: `uv run wisemonkey`
+- Build: `uv build`
+- Entry point: `agent.__main__:main` → `wisemonkey` CLI command
+
+## Testing
+
+Tests use the standard library `unittest` framework. Test files live in `tests/` at the project root, each mirroring the source module it tests.
+
+### Test Structure
+
+```
+tests/
+├── __init__.py
+├── conftest.py          # Shared fixtures (mock config, temp dirs, singleton resets)
+├── test_config.py       # Config singleton, load/save, dot-notation get/set
+├── test_core.py         # Workspace root finding, context file loading, prompt building
+├── test_memory.py       # Memory, ChatMemory persistence and trimming
+├── test_skills.py       # SkillLoader frontmatter parsing, load_all
+└── test_tools.py        # Tool registration, discovery, execution
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+python -m unittest discover -s tests -v
+
+# Run a specific test file
+python -m unittest tests.test_core -v
+
+# Run a specific test class
+python -m unittest tests.test_core.TestFindWorkspaceRoot -v
+
+# Run a single test
+python -m unittest tests.test_core.TestFindWorkspaceRoot.test_finds_agents_md_in_parent -v
+```
+
+### Key Patterns
+
+- **Reset singletons** — `Config` and `Memory` are singletons; reset them in `setUp`/`tearDown` or via fixtures (`Config._instance = None`, `Memory._instance = None`).
+- **Use `tempfile.mkdtemp()`** — each test gets its own session directory for isolation.
+- **Mock the LLM router** — never hit real API endpoints in tests.
+- **`conftest.py`** — place shared fixtures here (temp dirs, mock config, singleton resets).
+
+## Conventions
+
+- Use `pathlib.Path` for filesystem operations
+- Follow XDG Base Directory spec for data/config paths
+- Use `rich` for all console output (via `agent.console`)
+- Tools return plain dicts or strings; the agent serializes as needed
+- Keep the agent loop in `agent/agent.py` separate from core logic in `agent/core.py`

wisemonkey-2026.6.16/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toni Sagrista Sellés
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wisemonkey-2026.6.16/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include config.yaml
+include install.sh
+include pyproject.toml
+recursive-include agent *.py
+recursive-include tools *.py
+recursive-include skills *.md

wisemonkey-2026.6.16/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: wisemonkey
+Version: 2026.6.16
+Summary: A simple, extensible, and hackable AI agent for the Linux and macOS terminal
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: anthropic>=0.70.0
+Requires-Dist: chromadb>=0.5.0
+Requires-Dist: ollama>=0.4.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: pymupdf>=1.24.0
+Requires-Dist: pypubsub>=4.0.7
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: textual>=2.0.0
+Requires-Dist: tiktoken>=0.13.0
+Requires-Dist: xdg-base-dirs>=6.0.2
+Description-Content-Type: text/markdown
+
+<h3 align="center"><img src="icon.png" alt="Wisemonkey" width="130px"><br>Wisemonkey - <i>A dead simple CLI agent for Linux and macOS</i></h3>
+
+<p align="center">
+<a href="https://codeberg.org/langurmonkey/wisemonkey/releases"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcodeberg.org%2Fapi%2Fv1%2Frepos%2Flangurmonkey%2Fwisemonkey%2Freleases%2Flatest&query=%24.tag_name&label=latest%20release" alt="Latest release" /></a>
+<a href="https://codeberg.org/langurmonkey/wisemonkey/issues"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcodeberg.org%2Fapi%2Fv1%2Frepos%2Flangurmonkey%2Fwisemonkey%2Fissues&query=%24.length&label=open%20issues" alt="Open issues" /></a>
+<a href="https://opensource.org/licenses/MPL-2.0"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg" alt="License: MPL2.0" /></a>
+<img alt="Static Badge" src="https://img.shields.io/badge/OS-Linux-blue">
+<img alt="Static Badge" src="https://img.shields.io/badge/OS-macOS-yellow">
+
+</p>
+
+---
+
+[Wisemonkey](https://tonisagrista.com/projects/wisemonkey) is a simple, open, and hackable AI agent for the Linux and macOS terminal. It connects to any service providing an OpenAI, Anthropic, or Ollama-compatible endpoint. It features **session management**, **persistent memory management**, **vector store** for document embedding, native and MCP **tools**, **skills**, and much more.
+
+<p align="center">
+<a href="https://asciinema.org/a/8cTlvnN0qFeyflLH" target="_blank"><img src="https://asciinema.org/a/8cTlvnN0qFeyflLH.svg" width="60%"/></a>
+</p>
+
+The sections of this document are:
+
+- [Quickstart](#quickstart)
+- [Run from source](#run-from-source)
+- [Configuration](#configuration)
+- [Usage and commands](#usage-and-commands)
+- [Global memory](#global-memory)
+- [Rolling chat memory](#rolling-chat-memory)
+- [Extend agent](#extend-agent)
+
+## Quickstart
+
+Wisemonkey has been tested to work on Linux and macOS.
+
+### Requirements
+
+- Python 3.13+
+- `uv` for dependency management
+
+### Installation
+
+Install the agent with:
+
+```bash
+curl -fsSL https://codeberg.org/langurmonkey/wisemonkey/raw/branch/master/install.sh | bash
+```
+
+Launch the onboarding process to configure the agent interactively:
+
+```bash
+wisemonkey --onboard
+```
+
+### Running
+
+Run the agent with the default session:
+
+```bash
+wisemonkey
+```
+
+If you need an API key to access the endpoint, put it in the `.env` file. Wisemonkey looks for the `.env` file in the following locations, in order:
+
+- Current directory, `./.env`
+- Config directory, `$XDG_CONFIG_HOME/wisemonkey/.env`
+- Home directory, `$HOME/.env`
+
+Create the `.env` file with the API key:
+
+```bash
+echo "OPENAI_API_KEY=your-api-key-here" > .env
+echo "ANTHROPIC_API_KEY=your-api-key-here" > .env
+echo "OLLAMA_API_KEY=your-api-key-here" > .env
+```
+
+> The agent uses `python-dotenv` to load `.env` at startup. The `openai` package reads `OPENAI_API_KEY` from the environment automatically. You can also set `OPENAI_API_KEY` in your shell profile. Same goes for `ANTHROPIC_API_KEY` and `OLLAMA_API_KEY`.
+
+
+## Run from source
+
+```bash
+# Clone the repo, then build the project:
+uv build
+# Set API key:
+export OPENAI_API_KEY=your-api-key
+# Run the agent with the default session:
+uv run wisemonkey
+```
+
+## Configuration
+
+You can configure the agent interactively before the first run with `wisemonkey --onboard`. On first run, the configuration file is created in `$XDG_CONFIG_HOME/wisemonkey/config.yaml` from the default configuration (`config.yaml`) in the root of this repository.
+
+Additionally, the configuration directory holds the `mcp.json` (see next section), and the `.updates.yml`, which holds information about the last update time and status.
+
+### Model Context Protocol (MCP)
+
+Wisemonkey also supports MCP. Use the following commands to manage the MCP integration:
+
+- `/mcp`: Show the current MCP configuration
+- `/mcp edit`: Edit the MCP configuration file (`~/.config/wisemonkey/mcp.json`)
+- `/mcp tools`: List all MCP tools available. Alias: `/tools mcp`
+
+MCP servers are started when the agent boots. You need to restart the agent if you add new servers.
+
+## Usage and commands
+
+Run the agent, and then you can enter your prompt. You can use the following key bindings during input:
+
+- <kbd>Alt</kbd> + <kbd>Enter</kbd>: add a new line
+- <kbd>Enter</kbd>: submit the prompt
+- <kbd>Ctrl</kbd> + <kbd>q</kbd>: quit
+
+During inference, you can cancel the turn and return to the input prompt with <kbd>Ctrl</kbd> + <kbd>c</kbd>
+
+### Sessions
+
+Internally, Wisemonkey uses sessions to separate different memory histories. Sessions are **named by the user**. By default, the agent uses the `default` session. You can start in a different session (either create a new one, or restore it if it exists) by passing its name as a positional argument:
+
+```bash
+# Start in a specific session named 'my-project'
+wisemonkey my-project
+```
+
+The default session's name is `default`, so the following two commands are equivalent:
+```bash
+# These two commands start the 'default' session
+wisemonkey
+wisemonkey default
+```
+
+You can also list the existing sessions with `-ls`:
+
+```bash
+# List sessions
+wisemonkey --ls           
+Sessions:
+- my-project - ~/.local/share/wisemonkey/sessions/my-project
+- default - ~/.local/share/wisemonkey/sessions/default
+```
+
+Sessions contain:
+
+- The input history
+- Chat memory (see [chat memory](#chat-memory))
+- Vector store (see [document embedding](#document-embedding))
+- Notes (see [session memory](#session-memory))
+- User profile (see [session memory](#session-memory))
+
+For now, the configuration file is the same for all sessions.
+
+> Sessions are matched by the directory name in the sessions location (`~/.local/share/wisemonkey/sessions`). You can rename a session by just renaming the directory! 
+
+### `vi` mode
+
+You can enable `vi` mode for the current session with the [command](#commands) `/vi on`, or permanently in the [configuration](#configuration).
+
+**External editor**---In `vi` mode, exit INSERT mode (<kbd>Esc</kbd>), then press <kbd>v</kbd> to edit your prompt in an external editor (uses your `$VISUAL` or `$EDITOR` variable).
+
+### Slash commands
+
+There are a few commands available to use in the agent loop. You can list them with `/help`. Also, use `/[command-name] help` (e.g. `/config help`) to show additional help for a command.
+
+## Session memory
+
+Persistent memory follows XDG Base Directory spec in `~/.local/share/wisemonkey/session/$SESSION_NAME`:
+
+- `user_profile.json`---User information
+- `notes.json`---Persistent notes (added via `save_note` tool)
+
+**Lifecycle:**
+- Memory is loaded into the system prompt each turn
+- `save_note` tool adds notes during a session
+- `save_memory` tool explicitly persists memory to disk
+- Memory is auto-saved when the agent exits (interactive mode)
+
+## Document embedding
+
+Wisemonkey can embed documents into a per-session vector store, allowing the agent to search and reference their contents during conversation. Use `/embed` to add a document:
+
+```bash
+/embed ~/documents/research_paper.pdf
+/embed ./notes.md
+```
+
+The agent uses the `search_knowledge` tool to query embedded documents when answering questions about previously indexed files. Supported formats include PDF, Markdown, and plain text. Embeddings are powered by the configured embedding model and stored in the session directory under `vectordb/`.
+
+## Chat memory
+
+In addition to persistent memory, the agent maintains a **chat history** of recent user input and assistant output pairs. This provides context that survives beyond the LLM's context window. Here is how it works:
+
+- Each user message and assistant response is stored in memory
+- Reasoning is omitted from chat memory
+- Automatically compacted when exceeding the configured character limit
+- The user can trigger the compaction any time with `/memory compact`
+- Chat memory is attached to the system prompt on each turn
+- The agent displays the last 10 exchanges, with long messages truncated
+
+**Persistence:**
+- Chat history is persisted to `~/.local/share/wisemonkey/session/$SESSION_NAME/chat_history.json`
+- Automatically loaded on startup
+- Saved after every exchange (user input or assistant response)
+- Compacted history is also persisted to disk
+
+**Configuration:**
+```yaml
+agent:
+  max_chat_history: 128000  # Maximum history characters to keep for context
+```
+
+## Structure
+
+Wisemonkey is built to be modular and hackable. Here is an overview of the main parts and their mapping to the file system.
+
+```
+wisemonkey/
+├── agent/                  # Core agent code.
+│   ├── agent.py            # Main agent loop, prompt handling, key bindings.
+│   ├── commands.py         # Slash commands (e.g. /embed, /quit).
+│   ├── config.py           # Configuration loading and handling.
+│   ├── console.py          # Rich console output with themed formatting.
+│   ├── core.py             # Core agent functions, like API connection and tool calls.
+│   ├── mcp.py              # MCP server support.
+│   ├── memory.py           # Session memory, paste file creation.
+│   ├── router.py           # API router implementation for OpenAI, Ollama, and Anthropic.
+│   ├── skills.py           # Skill loading and management.
+│   ├── tools.py            # Tool definitions.
+│   ├── update.py           # Update management.
+│   ├── utils.py            # Utility functions.
+│   └── vectorstore.py      # Vector store wrapper.
+├── tools/                  # Tool implementations available to the model.
+│   ├── basic.py            # Basic and example tools.
+│   ├── files.py            # File read/write tools.
+│   ├── memory.py            # search_knowledge tool.
+│   ├── network.py          # URL fetching.
+│   ├── terminal.py         # Shell command execution.
+│   └── vectorstore.py      # Vector store tool handler.
+├── skills/                 # Skill definitions. Add new skills here.
+│   ├── example.md
+│   └── rolldice.md
+├── tests/                  # Contains all `unittest` tests.
+│   └── [...]
+├── config.yaml             # Default config file.
+├── README.md
+├── pyproject.toml
+├── install.sh              # Installer script.
+└── .env.example
+```
+
+## Extend the agent
+
+This agent is simple enough that it can be easily customized and extended by adding new tools, commands, and skills.
+
+If you create a cool new tool, skill, or slash command, consider contributing it via a merge request!
+
+### Adding tools
+
+Create a file in `tools/` or use one of the existing ones. To create a tool,
+create a method and decorate it with `@tool(name, description, params)`:
+
+```python
+from agent.tools import tool
+
+@tool(
+    name="my_tool",
+    description="Does something useful. Be exhaustive here, as it is what the LLM will read to know about your tool.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "input": {
+                "type": "string",
+                "description": "The input parameter."
+            }
+        },
+        "required": ["input"],
+    },
+)
+def my_handler(args):
+    input = args.get("input", "no input provided")
+    return {"result": f"{input}"}
+```
+
+Tools are auto-discovered on startup.
+
+### Adding slash commands
+
+The process is very similar to tools. You need to create your method, preferably in `agent/commands.py`, and decorate it with `@cmd(name, description, aliases, examples, can_complete)`.
+
+A slash command must return, in that order, `ok:bool`, `msg:str`, `content:str`, `markdown:str`:
+
+1. `ok`: a `bool` indicating if the command succeeded or failed.
+2. `msg`: an optional short status message. It is printed with `OK` or `ERROR`.
+3. `content`: an optional `str` with the Python Rich-formatted content, it is printed to the output.
+4. `markdown`: an optional `str` formatted in Markdown, it is printed to the output.
+
+```python
+@cmd(
+    "/my-command",
+    "This is the description",
+    aliases=["/mycmd"],
+)
+def _cmd_my_command(agent, params) -> (bool, str, str, str):
+    """This command returns a message but no content"""
+    return True, "This is awesome!", None, None
+```
+
+Decorated commands are automatically registered, and auto-completed in the input prompt.
+
+### Adding skills
+
+Add a `.md` file in `skills/` with YAML front matter, following the [agentskills.io](https://agentskills.io) standard:
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+# My skill
+
+## When to use
+
+...
+
+## Steps
+
+1. ...
+```
+
+The front matter `name` and `description` are parsed and shown in the
+skills list. The body is injected into the system prompt.