Build Agent Kurama: A Private Local Research Assistant with LangChain & Ollama

Agent Kurama is a lightweight research agent designed to run entirely on your local machine using LangChain and Ollama. It provides a private, feature-rich research environment powered by local large language models (LLMs). The agent integrates a broad suite of professional research tools, allowing it to pull data from Wikipedia, DuckDuckGo, Arxiv, Crossref, Europe PMC, and Open Library. It also supports Unpaywall for locating open-access links, alongside essential utilities for mathematics and date lookups.

By leveraging ChromaDB, Agent Kurama maintains a persistent memory system that stores and retrieves relevant research snippets. It can automatically append findings to a Markdown report, making it simple to organize and export your discoveries.

The agent is highly customizable. You can enable AskNews for real-time news updates, integrate SerpAPI for Google Search, or route queries through SearxNG for private metasearch. It also features a built-in long-text summarizer. The entire workflow is automated, covering analysis, query generation, research, reasoning, tool execution, report generation, and final previews.

Agent Kurama core capabilities

• Local LLM Chat: Powered by Ollama.
• Built-in Tools: Wikipedia, DuckDuckGo, Arxiv, Crossref, Europe PMC, Open Library, Unpaywall, math, and date utilities.
• Extended Tools: SerpAPI (Google via API), SearxNG (self-hosted metasearch), and specialized Markdown report functions (save_md_plus).
• Memory: Snippet storage and retrieval via a local ChromaDB directory.
• Optional Real-time News: AskNews integration (requires a free API key).
• Utilities: Local Markdown saving (save_md_locally) and long-text summarization (summarize_text).

System requirements

• OS: macOS or Linux (Windows users should use WSL).
• Language: Python 3.10 or higher.
• Prerequisite: Ollama installed and running.

Install Ollama

• macOS (via Homebrew):

brew install ollama
ollama serve

• Manual Download: Visit ollama.com

Pull the required models

• Chat model (referenced in agent.py):

ollama pull gpt-oss:120b-cloud

• Memory embedding model (referenced in retriever.py):

ollama pull nomic-embed-text

If the gpt-oss:120b-cloud model is unavailable, edit agent.py to use a standard model such as llama3:8b or qwen2:7b:

llm = ChatOllama(model="llama3:8b", temperature=0.7)

Local project setup

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

Optional configuration (recommended)

Create a .env file to configure AskNews, request headers, and optional web search tools. This prevents runtime errors during tool execution.

1. Configure AskNews (required for real-time news):

ASKNEWS_CLIENT_ID=your_client_id
ASKNEWS_CLIENT_SECRET=your_client_secret

If you do not need news features, remove asknews_search from the tools=[...] list in agent.py and delete the import line from tools.getNews import asknews_search.

2. Enable SerpAPI (Google search):

SERPAPI_API_KEY=your_serpapi_key

If not using this, remove serp_search from tools=[...] and delete from tools.serpSearch import serp_search.

3. Enable SearxNG (self-hosted metasearch):

SEARX_INSTANCE_URL=https://your_searx_instance_url
SEARX_TOP_K_RESULTS=5

If not using this, remove searx_search from tools=[...] and delete from tools.SearxNG import searx_search.

4. Set contact information (required by Unpaywall for polite User-Agent headers):

[email protected]
[email protected]

Run the project

Start the agent by running:

python agent.py

The terminal will display:

Ask Kurama 🦊

Enter your research question. Kurama will proceed through several stages: analysis → prompt generation → research → reasoning → information gathering → tool usage → report saving → report preview.

Data storage locations

• Vector Database: Data is stored in the ./chromadb_store folder (created automatically). Delete this folder to reset the agent's memory.
• Markdown Reports: Files generated by the tools are saved in the ./LocalStore directory (created automatically).

Run tests

The tests/ directory contains validation cases. Install pytest and run the suite:

pip install -U pytest
pytest -k "not asknews"  # Use this to skip news tests if your .env is not configured

Troubleshooting

1. "Model not found" – Ensure you have executed ollama pull gpt-oss:120b-cloud and ollama pull nomic-embed-text. If a specific model is missing from the library, update agent.py to a model you have downloaded (e.g., llama3:8b).

2. "AskNews Error / Missing env" – Ensure ASKNEWS_CLIENT_ID and ASKNEWS_CLIENT_SECRET are present in your .env file, or disable the AskNews tool in the code.

3. "Ollama not running" – Execute ollama serve to start the background service. On macOS, you can also launch the Ollama application.

4. ChromaDB issues – If you encounter database errors, delete the chromadb_store folder and restart the agent to initialize a fresh database.