{"id":14964696,"url":"https://github.com/turing-machines/mentals-ai","last_synced_at":"2025-04-08T10:27:28.111Z","repository":{"id":242546455,"uuid":"763806185","full_name":"turing-machines/mentals-ai","owner":"turing-machines","description":"No code AI agents","archived":false,"fork":false,"pushed_at":"2025-01-16T09:17:43.000Z","size":26018,"stargazers_count":428,"open_issues_count":10,"forks_count":44,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-01T09:25:17.152Z","etag":null,"topics":["ai","ai-agents","artificial-intelligence","cli","gpt","gpt-4o","llama3","llm","machine-learning","openai","terminal"],"latest_commit_sha":null,"homepage":"https://x.com/mentals_ai","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turing-machines.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-27T00:22:57.000Z","updated_at":"2025-03-28T21:47:32.000Z","dependencies_parsed_at":"2024-06-05T19:05:36.246Z","dependency_job_id":"05aaecb6-7e40-4684-b50d-91fb3b8d8e77","html_url":"https://github.com/turing-machines/mentals-ai","commit_stats":{"total_commits":93,"total_committers":4,"mean_commits":23.25,"dds":"0.19354838709677424","last_synced_commit":"71a316f35e3186d3cd27f73aa61f720cfbda042d"},"previous_names":["turing-machines/mentals-ai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turing-machines%2Fmentals-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turing-machines%2Fmentals-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turing-machines%2Fmentals-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turing-machines%2Fmentals-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turing-machines","download_url":"https://codeload.github.com/turing-machines/mentals-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247814898,"owners_count":21000664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","artificial-intelligence","cli","gpt","gpt-4o","llama3","llm","machine-learning","openai","terminal"],"created_at":"2024-09-24T13:33:39.589Z","updated_at":"2025-04-08T10:27:28.062Z","avatar_url":"https://github.com/turing-machines.png","language":"C++","funding_links":[],"categories":["\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","🚀 AI Tools for Vim, Neovim, and Terminal"],"sub_categories":[],"readme":"Mentals AI is a tool designed for creating and operating agents that feature **`loops`**, **`memory`**, and various **`tools`**, all through straightforward **`markdown`** files with a .gen extension. Think of an agent file as an executable file. You focus entirely on the logic of the agent, eliminating the necessity to write scaffolding code in Python or any other language. Essentially, it redefines the foundational frameworks for future AI applications 🍓\n\n\u003e [!NOTE] \n\u003e * [work in progress] A local vector database to store your chats with the agents as well as your private information. See [memory](https://github.com/turing-machines/mentals-ai/tree/memory) branch.\n\u003e * [work in progress] Web UI with agents, tools, and vector storage\n\n- [Getting Started](#-getting-started)\n- [Differences from Other Frameworks](#-differences-from-other-frameworks)\n- [Key Concepts](#️-key-concepts)\n    - [Instruction (prompt)](#-instruction-prompt)\n    - [Working Memory (context)](#-working-memory-context)\n    - [Short-Term Memory (experimental)](#-short-term-memory-experimental)\n    - [Control flow: From strings to algorithms](#️-control-flow-from-strings-to-algorithms)\n- [Roadmap](#️-roadmap)\n- [The Idea](#-the-idea)\n\n## 📌 Examples\n\nWord chain game in a self-loop controlled by LLM:\n![Word Chain game in a loop](assets/word_chain.gen.gif)\n\n\u003e NLOP — Natural Language Operation\n\nOr more complex use cases:\n| 🔄 Any multi-agent interactions | 👾 Space Invaders generator agent | 🍄 2D platformer generator agent |\n|--------------------|-----------|--------------|\n|![react](assets/react.png) | ![space_invaders.gen](assets/space_invaders.gif) | ![mario.gen](assets/mario.gif) |\n\nOr help with the content:\n- Collect YouTube videos on a given topic and save them to a .csv file with the videos, views, channel name, and link;\n- Get the transcription from the video and create a table of contents;\n- Take top news from Hacker News, choose a topic and write an article on the topic with the participation of the critic, and save to a file.\n\nAll of the above examples are located in the [agents](agents) folder.\n\n\u003e [!NOTE]\n\u003e Llama3 support is available for providers using a compatible OpenAI API.\n\n## 🚀 Getting Started\n\nBegin by securing an OpenAI API key through the creation of an  [OpenAI\naccount](https://platform.openai.com/docs/quickstart?context=node). If you already have \nan API key, skip this step.\n\n### 🏗️ Build and Run\n\n**Prerequisites**\n\nBefore building the project, ensure the following dependencies are installed:\n\n- libcurl: Used for making HTTP requests\n- libfmt: Provides an API for formatting\n- pgvector: Vector operations with PostgreSQL\n- poppler: Required for PDF processing\n\nDepending on your operating system, you can install these using the following commands:\n\n**Linux**\n\n```shell\nsudo apt-get update\nsudo apt-get install libcurl4-openssl-dev libfmt-dev libpoppler-dev\n```\n\n**macOS**\n\n```shell\nbrew update\nbrew install curl fmt poppler\n```\n\n**Windows**\n\nFor Windows, it's recommended to use vcpkg or a similar package manager:\n\n```shell\nvcpkg install curl fmt poppler\n```\n\n**pgvector installation**\n\n\u003e [!NOTE]\n\u003e In the `main` branch you can skip this step\n\n- [Build from sources](https://github.com/pgvector/pgvector?tab=readme-ov-file#installation)\n- [Docker, Homebrew, PGXN, APT, etc.](https://github.com/pgvector/pgvector?tab=readme-ov-file#additional-installation-methods)\n\n\n**Clone the repository**\n```shell\ngit clone https://github.com/turing-machines/mentals-ai\ncd mentals-ai\n```\n\n**Configuration**\n\nPlace your API key in the `config.toml` file:\n\n```bash\n[llm]\n# OpenAI\napi_key = \"\"\nendpoint = \"https://api.openai.com/v1\"\nmodel = \"gpt-4o\"\n```\n\n**Build the project**\n\n```bash\nmake\n```\n\n**Run**\n\n```shell\n./build/mentals agents/loop.gen -d\n```\n\n## 🆚 Differences from Other Frameworks\n\nMentals AI distinguishes itself from other frameworks in three significant ways:\n\n* The `Agent Executor` 🧠 operates through a recursive loop. The LLM determines the next steps: selecting instructions (prompts) and managing data based on previous loops. This recursive decision-making process is integral to our system, outlined in [mentals_system.prompt](mentals_system.prompt)\n* Agents of any complexity can be created using `Markdown`, eliminating the need for traditional programming languages. However, Python can be integrated directly into the agent's `Markdown` script if necessary.\n* Unlike platforms that include preset reasoning frameworks, Mentals AI serves as a blank canvas. It enables the creation and integration of your own reasoning frameworks,  including existing ones: `Tree of Thoughts`, `ReAct`, `Self-Discovery`, `Auto-CoT`, and others. One can also link these frameworks together into more complex sequences, even creating a network of various reasoning frameworks.\n\n## 🗝️ Key Concepts\n\nThe agent file is a textual description of the agent instructions with a `.gen` extension.\n\n### 📖 Instruction (prompt)\n\nInstruction is the basic component of an agent in Mentals. An agent can consist of one or more instructions, which can refer to each other. \n\n\u003cimg src=\"assets/instructions.png\" width=\"500\"\u003e\n\nInstructions can be written in free form, but they always have a name that starts with the `#` symbol. The `## use:` directive is used to specify a reference to other instructions. Multiple references are listed separated by commas.\n\nBelow is an example with two instructions `root` and `meme_explain` with a reference:\n\n```\n# root\n## use: meme_explain\n\n1. Create 3 memes about AGI;\n2. Then do meme explain with meme per call;\n3. Output memes and their explanations in a list.\n\n# meme_explain\n\nExplain the gist of the meme in 20 words in medieval style.\nReturn explanation.\n```\n\nIn this example, the `root` instruction calls the `meme_explain` instruction. The response from meme_explain is then returned to the instruction from which it was called, namely the root.\n\nAn instruction can take an `input` parameter, which is automatically generated based on the context when the instruction is called. To specify the input data more precisely, you can use a *free-form prompt* in the `## input:` directive, such as a JSON object or `null`.\n\nUsing a document for input:\n```\n# some_instruction\n## input: design document only\n```\n\nUsing a JSON object as input:\n```\n# duckduckgo\n## input: { search_query: search query, search_limit: search limit }\n\nWrite a Python script to search in DuckDuckGo.\nSimulate request headers correctly e.g. user-agent as Mozilla and Linux.\n```\n\n\u003e [!NOTE]\n\u003e Instruction calls are implemented independently from function or tool calls at OpenAI, enabling the operation of agents with models like Llama3. The implementation of instruction calls is transparent and included in the mentals_system.prompt file.\n\n#### 🛠️ Tool\n\nTool is a kind of instruction. Mentals has a set of native tools to handle message output, user input, file handling, Python interpreter, Bash commands, and Short-term memory.\n\nAsk user example:\n```\n# root\n## use: user_input\n\nAsk user name.\nThen output: `Welcome, user_name!`\n```\n\nFile handling example:\n```\n# root\n## use: write_file, read_file\n\nWrite 'Hello world' to a file.\nThen read and output file content.\n```\n\nThe full list of native tools is listed in the file `native_tools.toml`.\n\n\n### 🧠 Working Memory (context)\n\nEach instruction has its own working memory — context. When exiting an instruction and re-entering it, the context is kept by default. To clear the context when exiting an instruction, you can use the `## keep_context: false` directive:\n\n```\n# meme_explain\n## keep_context: false\n\nExplain the gist of the meme in 20 words in medieval style.\nReturn explanation.\n```\n\nBy default, the size of the instruction context is not limited. To limit the context, there is a directive `## max_context: number` which specifies that only the `number` of the most recent messages should be stored. Older messages will be pushed out of the context. This feature is useful when you want to keep the most recent data in context so that older data does not affect the chain of reasoning.\n\n```\n# python_code_generation\n## input: development tasks in a list\n## use: write_file\n## max_context: 5\n\nDo all development tasks in a loop: task by task.\nSave the Python code you implement in the main.py file.\n```\n\n### ⏳ Short-Term Memory (experimental)\n\nShort-term memory allows for the storage of intermediate results from an agent's activities, which can then be used for further reasoning. The contents of this memory are accessible across all instruction contexts.\n\nThe `memory` tool is used to store data. When data is stored, a keyword and a description of the content are generated. In the example below, the `meme_recall` instruction is aware of the meme because it was previously stored in memory.\n\n```\n# root\n## use: memory, meme_recall\n\nCome up with and memorize a meme.\nCall meme recall.\n\n# meme_recall\n## input: nothing\n\nWhat the meme was about?\n```\n\n### ⚙️ Control flow: From strings to algorithms\n\nThe control flow, which includes conditions, instruction calls, and loops (such as `ReAct`, `Auto-CoT`, etc.), is fully expressed in natural language. This method enables the creation of `semantic conditions` that direct data stream branching. For instance, you can request an agent to autonomously play a word chain game in a loop or establish an ambiguous exit condition: `exit the loop if you are satisfied with the result`. Here, the language model and its context determine whether to continue or stop. All this is achieved without needing to define flow logic in Python or any other programming language.\n\n#### ⚖️ Reason Action (ReAct) example\n\n```\n## use: execute_bash_command, software_development, quality_assurance\n\n...\nYou run in a loop of \"Thought\", \"Action\", \"Observation\".\nAt the end of the loop return with the final answer.\nUse \"Thought\" to describe your thoughts about the task \nyou have been asked. Use \"Action\" to run one of the actions \navailable to you. Output action as: \"Action: action name to call\".\n\"Observation\" will be the result of running those actions.\n\nYour available actions:\n- `execute_bash_command` for util purposes e.g. make directory, install packages, etc.;\n- `software_development` for software development and bug-fixing purposes;\n- `quality_assurance` for QA testing purposes.\n...\n```\n\n#### 🌳 Tree of Thoughts (ToT) example\n\nThe idea behind ToT is to generate multiple ideas to solve a problem and then evaluate their value. \nValuable ideas are kept and developed, other ideas are discarded.\n\nLet's take the example of the 24 game. The 24 puzzle is an arithmetical puzzle in which \nthe objective is to find a way to manipulate four integers so that the end result is 24.\nFirst, we define the instruction that creates and manipulates the tree data structure. \nThe model knows what a tree is and can represent it in any format, from plain text to XML/JSON or any custom format.\n\nIn this example, we will use the plain text format:\n\n```\n# tree\n## input: e.g. \"add to node `A` child nodes `B` and `C`\", \"remove node `D` with all branches\", etc. \n## use: memory\n## keep_context: false\n\nBuild/update tree structure in formatted text.\n\nUpdate the tree structure within the specified action;\nMemorize the final tree structure.\n```\n\nNext, we need to initialize the tree with initial data, let's start with the root instruction:\n\n```\n# root\n## use: tree\n\nInput: 4 5 8 2\nGenerate 8 possible next steps.\nStore all steps in the tree as nodes e.g. \nNode value 1: \"2 + 8 = 10 (left: 8 10 14)\"\nNode value 2: \"8 / 2 = 4 (left: 4 8 14)\"\netc.\n```\n\nCalling the root instruction will suggest 8 possible next steps to calculate with the first 2 numbers and store these steps as tree nodes. Further work by the agent results in the construction of a tree that is convenient for the model to understand and infer the final answer.\n\n```\n4 5 8 2\n├── 4 + 5 = 9 (left: 9, 8, 2)\n│   └── discard\n├── 4 + 8 = 12 (left: 12, 5, 2)\n│   └── discard\n├── 4 + 2 = 6 (left: 6, 5, 8)\n│   └── discard\n├── 5 + 8 = 13 (left: 13, 4, 2)\n│   └── discard\n├── 5 + 2 = 7 (left: 7, 4, 8)\n│   └── (7 - 4) * 8 = 24\n├── 8 + 2 = 10 (left: 10, 4, 5)\n│   └── discard\n├── 4 * 5 = 20 (left: 20, 8, 2)\n│   └── (20 - 8) * 2 = 24\n└── 4 * 8 = 32 (left: 32, 5, 2)\n    └── discard\n\nBased on the evaluations, we have found two successful paths to reach 24:\n\n1. From the node \"5 + 2 = 7 (left: 7, 4, 8)\", we have the equation: (7 - 4) * 8 = 24.\n2. From the node \"4 * 5 = 20 (left: 20, 8, 2)\", we have the equation: (20 - 8) * 2 = 24.\n\nThus, the final equations using all given numbers from the input are:\n1. (5 + 2 - 4) * 8 = 24\n2. (4 * 5 - 8) * 2 = 24\n```\n\nA complete example is contained in the [agents/tree_structure.gen](agents/tree_structure.gen)\n\n\n## 🗺️ Roadmap\n\n- [ ] Web UI -- WIP\n- [ ] Vector database tools -- WIP\n- [ ] Agent's experience (experimental)\n- [ ] Tools: Image generation, Browser\n\n\n## ✨ The Idea\n\nThe concept originated from studies on psychoanalysis [Executive functions](https://en.wikipedia.org/wiki/Executive_functions), [Exploring Central Executive, Alan Baddeley, 1996](https://www.krigolsonteaching.com/uploads/4/3/8/4/43848243/baddeley_1996.pdf). He described a system that orchestrates cognitive processes and working memory, facilitating retrievals from long-term memory. The LLM functions as `System 1`, processing queries and executing instructions without inherent motivation or goal-setting. So, what then is `System 2`? Drawing from historical insights now reconsidered through a scientific lens:\n\n\u003e The central executive, or executive functions, is crucial for controlled processing in working memory. It manages tasks including directing attention, maintaining task objectives, decision-making, and memory retrieval.\n\nThis sparks an intriguing possibility: constructing more sophisticated agents by integrating `System 1` and `System 2`. The LLM, as the cognitive executor `System 1`, works in tandem with the Central Executive `System 2`, which governs and controls the LLM. This partnership forms the dual relationship foundational to Mentals AI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturing-machines%2Fmentals-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturing-machines%2Fmentals-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturing-machines%2Fmentals-ai/lists"}