Core Concepts

Agents

Engram ships seven autonomous workers. Scheduled agents run via AsyncIOScheduler inside the FastAPI process — no separate worker container required. On-demand agents are invoked from the shell, editor, or API.

How Agents Work

All agents share the same inference stack: they call POST /api/chat internally, which routes the request to Ollama running on your local hardware. No agent makes an outbound call to an AI API. Third-party integrations (Google, Linear, Jira) communicate directly with their respective APIs from your machine — Engram does not proxy credentials.

# Simplified agent execution flow

Agent → reads memory (Qdrant local) → calls Ollama (local) → writes result → optional 3rd-party API

# ↑ encrypted ↑ on-device ↓ audit log

audit_writer → appends HMAC-chained record via Unix socket

Audit trail

Every agent action is recorded in the tamper-evident HMAC audit chain. The audit_writer process is the sole writer — application code appends via a Unix socket, preventing any process from backdating or modifying historical records.

All Agents

Calendar Agent

Available⏱ Every 15 min

Reads your Engram memories for explicit scheduling intent (e.g. 'meet Alex tomorrow at 3pm') and creates Google Calendar events. Does not read back from the calendar.

Requires:GOOGLE_CALENDAR_CREDENTIALS

Email Agent

Available⏱ Every 60 min

Reads unread Gmail threads, drafts context-aware replies using Llama 3.1, and saves them to Drafts. Never sends automatically — always human-in-the-loop.

Requires:GMAIL_CREDENTIALS

Terminal Genie

Available⏱ On demand

Shell function that intercepts failed commands and suggests a corrected version from Llama 3.1. Invoked via the `??` alias in Zsh or Bash.

No API keys required

Git Automator

Available⏱ On demand

Three git aliases: `g-commit` generates semantic commit messages from diffs, `g-pr` writes Markdown PR descriptions, `g-check` scans staged files for leaked secrets.

No API keys required

DocSpider

Available⏱ On demand

BFS web crawler that ingests external documentation sites into the local Qdrant `doc_knowledge` collection. Point it at any URL and it builds an offline RAG knowledge base.

No API keys required

Daily Briefing

Coming Soon⏱ Configurable (default 8 AM)

Will synthesise high-priority Linear/Jira tasks, today's calendar events, and recent memories into a structured morning digest inside the dashboard.

Requires:LINEAR_API_KEYJIRA_BASE_URLJIRA_EMAILJIRA_API_TOKEN

Jarvis (Voice Mode)

Available⏱ On demand

Records 5-second audio clips, transcribes locally via OpenAI Whisper (no cloud API), sends to /chat, and reads the reply aloud via macOS `say`. Press Enter to speak.

No API keys required

Adding a Custom Agent

Register a new scheduled agent by adding a job to core/scheduler.py. The function runs in the FastAPI process — it has direct access to the memory client and Ollama without any additional setup.

python

# core/scheduler.py
from apscheduler.schedulers.asyncio import AsyncIOScheduler
from core.memory import MemoryClient

scheduler = AsyncIOScheduler()

@scheduler.scheduled_job("interval", minutes=30, id="my_custom_agent")
async def my_custom_agent():
    client = MemoryClient()
    memories = await client.search("relevant context", limit=5)
    # ... call Ollama, write result back to memory ...
    await client.store({"type": "agent_result", "content": result})

Opt-in only

Agents that require third-party credentials will silently skip execution if the relevant environment variables are not set. You can safely run Engram without any Google or Linear credentials — only the local-only agents will run.