go-magnetar

An AI chat agent with an integrated knowledge base and customizable skills. A single standalone binary with everything included — no dependencies to install, no go install needed. Just download, run, and start chatting with any OpenAI-compatible LLM, indexing documents and web pages into a local vector database, and get answers grounded in your own content.

What it does

• Chat — interactive REPL with multi-turn conversation and automatic context compaction
• Index — /index adds documents to your RAG knowledge base (optional)
• Fetch — /fetch retrieves and displays web content as Markdown
• Skills — customize agent behavior with reusable skill files for specialized tasks
• Integrations — Confluence, JIRA, GitHub, GitLab (all optional, disabled by default)

Supported file formats: .md, .txt, .csv, .tsv, .docx, .pdf, .odt, .pptx, .xlsx, .html, .eml.

Requirements

• Go 1.27.3 (or download a pre-built binary)
• API key for any OpenAI-compatible provider (OpenAI, Azure OpenAI, Ollama, etc.)

Note: Qdrant is no longer required. The default vector store is Chromem (built-in, in-memory with optional persistence). Qdrant is available as an optional external store for production deployments.

Vector Stores

go-magnetar supports two vector storage backends:

Chromem (default)

• Built-in: No external dependencies required
• In-memory by default: Store exists only during session (when rag.chromem.data_dir is empty)
• Persistent mode: Set rag.chromem.data_dir to persist vectors to disk
• Use case: Local development, testing, edge deployments

Qdrant (external)

• External server: Requires running Qdrant container
• Full persistence: Automatic disk persistence with advanced filtering
• Use case: Production, large-scale deployments

Switch between stores via config:

rag:
  store:
    type: chromem  # or qdrant

See docs/architecture.md for vector store architecture details.

Quick start

1. Install

Option A — pre-built binary (recommended):

Download a single standalone binary from GitHub Releases and place it in your $PATH.

Why a single binary? go-magnetar is distributed as a single self-contained binary with all dependencies compiled in. No need to install Go, manage dependencies, or worry about version conflicts. Just download, make executable, and run — everything you need is already there.

Option B — go install:

go install github.com/wmentor/go-magnetar/cmd/go-magnetar@latest

Option C — build from source:

git clone https://github.com/wmentor/go-magnetar.git
cd go-magnetar
make build          # binary → bin/go-magnetar

2. Configure

On first run, go-magnetar creates ~/.go-magnetar/config.yml automatically.

Edit it to set your LLM API key and model:

version: "1.0"
language: english
verbose: true
profile: default

profiles:
  default:
    llm:
      base_url: https://api.openai.com/v1
      api_key: $env:OPENAI_API_KEY   # or paste the key directly
      model: gpt-4o
      context: 128000
      temperature: 0.9

For a complete list of options see docs/configuration.md.

3. Run

go-magnetar

This opens the interactive chat REPL. Type a question and press Enter:

> What is the capital of France?
Paris is the capital of France.

> /help
...

> ^D   ← Ctrl+D or /exit to quit

Project Context (AGENTS.md / CLAUDE.md)

If a file named AGENTS.md or CLAUDE.md exists in the current directory, its content is automatically loaded into the agent’s system prompt. This allows you to define project-specific instructions, conventions, and context.

• Priority: AGENTS.md takes precedence over CLAUDE.md. If both files exist, only AGENTS.md is loaded.
• Use cases: Custom instructions, coding standards, project-specific guidelines, API documentation, etc.

Example AGENTS.md:

You are an expert developer working on my-project. Follow these rules:
- Always write unit tests for new code
- Use Go 1.27+ features when appropriate
- Follow the project's coding style as documented in docs/style.md

The content is appended to the system prompt as a section titled “Project context”. See docs/agent_tools.md for more information.

What the agent can do

Beyond answering questions, the agent has access to tools it can call automatically:

For a complete list of tools and their detailed documentation, see docs/agent_tools.md.

The agent picks tools automatically based on your question. You don’t need to specify which tool to use.

Skills

Skills are reusable files that customize the agent’s behavior for specific tasks:

• Custom instructions — Define specialized workflows for coding, writing, research, etc.
• Templates — Enforce consistent output formats (e.g., bug reports, feature requests)
• Project-specific guidance — Tailor the agent to your project’s conventions
• Enable/disable per project — Override user-level skills with project-specific ones

Skills are stored in:

• User skills: ~/.go-magnetar/skills/ — global skills
• Project skills: {current_dir}/.go-magnetar/skills/ — project-specific skills (takes priority)

Example skill file structure:

my-skill/
└── SKILL.md

SKILL.md content:

---
name: coding-assistant
description: Programming assistant with Go expertise
disable: false
---

You are an expert Go developer...

Usage:

> /skill coding-assistant

See docs/skill.md for complete skill documentation.

Using the knowledge base (RAG)

The RAG feature is optional. Enable it when you want the agent to answer questions based on your own documents.

Enable RAG in config

By default, RAG uses Chromem (built-in, in-memory). For persistent storage, set rag.chromem.data_dir:

rag:
  enable: true
  store:
    type: chromem  # or qdrant
  llm:
    base_url: https://api.openai.com/v1
    api_key: $env:OPENAI_API_KEY
    model: text-embedding-3-small
    vector_size: 1536
  chromem:
    data_dir: ~/.go-magnetar/store  # optional: set for persistence
    collection: documents  # collection name

The main ~/.go-magnetar/config.yml already includes plugins/rag.yml via the include directive — no changes to it are needed.

For Qdrant (external store), use:

rag:
  enable: true
  store:
    type: qdrant
  llm:
    base_url: https://api.openai.com/v1
    api_key: $env:OPENAI_API_KEY
    model: text-embedding-3-small
    vector_size: 1536
  qdrant:
    connstr: http://localhost:6333
    collection: documents

Start Qdrant (optional, only if using Qdrant store)

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

Index documents

go-magnetar
> /index docs/guide.md
> /index https://example.com/article
> /index https://your-domain.atlassian.net/wiki/spaces/SPACE/pages/123456
> /index https://jira.example.com/browse/PROJECT-123

The agent will now search the knowledge base before answering any question.

Chat commands

Use ↑/↓ arrow keys to navigate command history (stored in ~/.go-magnetar-history.json).

Sessions

Save the current conversation to a file and restore it later:

> /session.save /tmp/my-session.json

# Resume later
go-magnetar --session /tmp/my-session.json

Data Residency

go-magnetar offers 100% local processing options:

• Chromem (built-in vector store) — no external dependencies
• Local LLMs (Ollama, lm-studio, etc.) — run on your machine
• Zero data exfiltration — everything stays on your computer

When configured with Chromem + local LLM, your documents, embeddings, and conversations never leave your machine.

See docs/data_residency.md for complete details.

Security

See docs/security.md for complete security information.

• Safety guard — dangerous commands (rm -rf /, sudo, git push, package managers, etc.) are blocked automatically. Enable with guard.enable: true in config.
• Read-only mode — toggle with /readonly to block all file writes and shell modifications for the session.
• Root user — go-magnetar refuses to run as root.
• Sensitive env vars — variables matching patterns like TOKEN, KEY, PASS, SECRET are stripped from the command environment before execution.

See docs/security.md for details.

CLI flags

# Non-interactive (scripting / batch)
go-magnetar -f questions.txt

# Load a saved session
go-magnetar --session session.json

# Use a named profile
go-magnetar -p production

# Run in read-only mode
go-magnetar --read-only

# Show the execution time of every answer
go-magnetar --enable-timing

Note: In -f mode, chat commands (/index, /fetch, etc.) are not available. Text preprocessor placeholders like {{date}}, {{uuid}}, {{file:path}} are expanded.

Documentation

• Configuration reference
• Chat commands
• Agent tools
• File format support
• Text preprocessor
• Skills
• Security
• Data Residency
• User manual

License

See LICENSE.