🧬 Identity and Channels

SOUL.md is the most important file in workspace/. It defines the assistant's name, pronouns, tone of voice (formal/casual), ethical values, response style, technical preferences, and even sense of humor.

A well-written SOUL.md transforms Jarvis from a generic chatbot into a partner with a consistent personality. It’s the difference between “How can I help?” and “Straight to the point: what’s stuck?”

Persona design, system prompt injection, consistent tone, values as guardrails, communication style.

AGENTS.md contains explicit behavior rules: always ask for confirmation before deleting files, never run code without review in autonomous mode, and prioritize security over speed.

Explicit rules are more reliable than expecting the LLM to "understand" what you want. AGENTS.md is your usage contract with the assistant.

Positive rules (ALWAYS), negative rules (NEVER), task priorities, escalation to a human.

USER.md contains information about the creator: name, favorite tech stack, company, time zone, and ongoing projects. Jarvis uses this to personalize every response.

Without USER.md, the assistant responds generically. With a well-filled-out USER.md, it suggests Python when you prefer Python, and knows you use Vim, not VS Code.

User profile, technical preferences, professional context, response personalization.

AIEOS is INTELECTO's identity export format. It lets you serialize the complete personality (SOUL + AGENTS + USER) in a single portable file.

You can have multiple Jarvis instances with different personalities — one for work, one for personal projects — and switch between them instantly.

Identity serialization, interchangeable profiles, personality import/export, multi-persona.

INTELECTO supports multiple SOUL.md profiles. You can have "Atlas-Dev" for coding (direct, technical), "Atlas-Meeting" for a corporate context (formal, diplomatic), and switch between them with a command.

Different contexts call for different tones. An assistant that only speaks one way is limited. Interchangeable profiles provide real flexibility.

Profile switching, context-aware personality, workspace profiles, identity hot-swapping.

Writing SOUL.md is an iterative process. You write, test it with real questions, observe unexpected responses, and refine the instructions until the behavior is consistent with what you want.

No SOUL.md is perfect in its first version. The refinement process is the most important prompt engineering skill for personal assistants.

Iterative prompt engineering, personality edge cases, consistency testing, tone calibration.

Telegram offers a robust API, polling or webhooks, file sending, inline buttons, and groups. It’s the easiest channel to configure and the most reliable for intensive personal use.

Most demos and real-world personal assistant use cases use Telegram. Mastering this channel first speeds up all the others—the BaseChannel pattern is the same.

BotFather, polling vs. webhook, inline keyboards, chat_id, allowed users, message types.

BaseChannel defines 3 abstract methods: start() initializes the connection, send(user_id, message) delivers the response, and stop() closes gracefully. Any platform that implements these 3 is a valid channel.

The Agent never knows which channel it’s using — it only calls send(). This abstraction lets you switch from Telegram to Discord in minutes without changing the Agent.

Abstract interface, adapter pattern, channel-agnostic agent, graceful shutdown.

WhatsApp via Meta Business API requires approval, but it's the most widely used channel in Brazil. INTELECTO implements WhatsAppChannel, which uses Meta webhooks to receive messages and the API to send them.

For professional use in Brazil, WhatsApp is indispensable. Having a Jarvis that responds on WhatsApp is a competitive advantage for freelancers and businesses.

Meta Business API, webhook verification, phone number ID, template messages, rate limits.

Discord and Slack are ideal channels for teams. DiscordChannel uses discord.py and supports slash commands. SlackChannel uses the Events API with OAuth for enterprise workspaces.

An assistant that lives in the team’s Discord/Slack answers everyone’s questions, automates workflows, and eliminates unnecessary meetings.

Bot permissions, slash commands, event subscriptions, workspace scopes, mention handling.

EmailChannel uses IMAP to monitor an inbox and SMTP to send replies. Jarvis can reply to emails automatically or generate drafts for human review.

Automatic email triage is one of the highest-ROI use cases. A Jarvis that categorizes, prioritizes, and replies to routine emails saves hours per week.

IMAP polling, MIME parsing, thread tracking, auto-reply vs draft, spam filtering.

VoiceChannel uses Whisper for real-time transcription. When it detects the configured wake word (e.g., "Atlas"), it sends the transcribed text to the Agent and synthesizes the response with TTS.

Voice is the most natural channel for interaction while you work. A Jarvis that listens and responds by voice makes your workflow hands-free.

Wake word detection, Whisper STT, TTS synthesis, VAD (voice activity detection), response latency.

FTS5 is SQLite’s full-text search module. No external dependencies, no server, no cost—just SQLite with highly optimized full-text search indexes.

Jarvis's memory needs to be quickly searchable. FTS5 automatically indexes all content and enables searches in milliseconds across thousands of records.

FTS5 virtual table, tokenization, inverted index, prefix search, phrase matching.

BM25 is the relevance ranking algorithm used by FTS5. When Jarvis searches for memories related to your message, BM25 ensures the most relevant ones appear first—not just the most recent ones.

Without relevance ranking, memory returns random results. BM25 is what makes Jarvis’s memory intelligent, rather than just a list of facts.

Term frequency, inverse document frequency, field weights, bm25() function in SQLite.

Layer 1: MEMORY.md in workspace/ — static bootstrap facts that are always in the system prompt. Layer 2: memory.db — dynamic facts extracted from conversations and retrieved by relevance when needed.

You can't put all the memory in the system prompt (expensive and slow). The 2-layer architecture solves this: the essentials are always present, and the history is retrieved on demand.

Context window management, RAG (retrieval augmented generation), bootstrap facts, dynamic retrieval.

Each entry in memory.db has a category: fact (a fact about the user or the world), conversation (an important excerpt from a past conversation), solution (how a problem was solved — very useful for avoiding rework).

Categories allow more specific searches. When you report a bug, Jarvis searches only category='solution' to see if it has already solved something similar.

Categorical filtering, solution memory, conversation threading, automatic fact extraction.

Before saving a new fact, store.py searches for similar facts with BM25. If the similarity is high, it updates the existing fact instead of creating a duplicate. This keeps memory from growing with redundant information.

Without deduplication, memory fills up with variations of the same fact. "User uses Python" and "User prefers Python" would be separate entries — deduplication merges them.

Similarity threshold, upsert pattern, cosine similarity alternative, fact merging.

When the memory database exceeds a configured limit, a compaction job summarizes old entries into denser facts. Keeps memory relevant without growing indefinitely.

Unlimited memory is a problem. Automatic compaction resolves the tension between "remembering everything" and "keeping search efficient".

Memory compaction, summarization, memory TTLs, strategic pruning, relevance decay.