There is an unspoken default assumption when building agents: tool results are important, and the model must read the full original text to continue reasoning. Recently, I found this assumption might be wrong.

https://github.com/maka-agent/maka-agent…
Welcome to star

In Maka, we aggressively pruned tool results — trimming the raw data returned by tools down to just key summaries — then ran full task comparisons. The conclusion was surprising: reasoning quality was almost unchanged, close to lossless compression.

Why is this? I have a few possible explanations:

First, the information has already been distilled into Assistant messages. The context structure of the Agent loop is:

System Prompt → User → Assistant → Tool Use → Tool Result → Assistant → …

After each tool result, the model outputs an Assistant message expressing its understanding and next decision. This is a semantic distillation — the raw data is compressed into a reasoning summary. In subsequent turns, the model is essentially talking to “its own understanding,” not the original tool result. Pruning the original text is like deleting an archive that has already been read and converted — the information is already gone, only the shell remains.

Second, attention is inherently sparse in long contexts. The “Lost in the Middle” study showed that Transformer attention weights decay significantly for content in the middle of a long context; the model focuses more on the beginning (system prompt) and recent turns. Tool results are typically in the middle of the context and have extremely low information density (500 lines of code, terminal output, redundant JSON). The model wasn’t really “reading” them carefully anyway. Pruning just explicitly removes content that was already implicitly ignored.

Third, the decision point has already passed. The model called the tool because it needed that information at that moment. But after 5 turns, that tool result is no longer marginal information — the core content has already been digested into the subsequent reasoning chain. Keeping the original text is “archiving,” not “decision input.”

Measurement data: For the same task (MIPS interpreter), Maka’s total token consumption is only 38% of OpenCode’s, but its output tokens are 2.7 times higher. Behind this gap are contributions from DeepSeek’s 95% cache hit rate and tool result pruning. Together, they create an order-of-magnitude leap in token economics for long-range tasks.

Implication for agent engineering: The bulkiest part of the context is not necessarily the most important part. Instead of focusing on “how to get the full tool result into the context,” focus on the “reasoning quality after the model has read it.” The true carrier of information is not the original text, but the understanding.

maka-agent/maka-agent

Source: https://github.com/maka-agent/maka-agent
ENGLISH

Maka

Maka is a local-first desktop AI workbench. It integrates model connections, conversations, tool permissions, file read/write, terminal execution, search, bot entry points, and run recovery into a single Electron application. The goal is to let users run an observable, controllable, and recoverable agent on their own computer.

This repository is under active development. This README serves two audiences:

• Users opening Maka for the first time: know why you need to configure AI first, where data is stored, and which capabilities are already available.
• Engineers continuing to develop Maka: quickly start, verify, locate key packages and design documents.

What you will see

When you first enter Maka, if no model connection is available, the welcome screen will guide you through AI configuration instead of showing an empty chat box that cannot send messages. The recommended path is:

1. Open Settings -> Model.
2. Choose a real model provider, fill in the API key, or log in to an already integrated account.
3. Test the connection and select the default model.
4. Return to the welcome screen and start your first conversation using the quick input.

Currently supported model types:

• Overseas APIs: Anthropic, OpenAI, Google Gemini.
• Domestic APIs: DeepSeek, Moonshot, Z.AI Coding Plan, Kimi Coding Plan.
• Local models: Ollama.
• Custom gateways: OpenAI Compatible endpoint.
• Account subscription entry points: Claude Subscription, Codex Subscription, Gemini CLI, etc. — they are listed separately according to their experimental/available status. Entry points that haven’t been integrated into the send pipeline are not disguised as usable.

Current capabilities

Maka is not a simple chat demo. It already has these core aspects:

• Desktop sessions: Create, switch, archive, search, rename, stop, retry, regenerate, branch from a turn.
• Model runtime: Provider runtime based on Vercel AI SDK, supports model streaming, tool calls, usage recording, error classification, and startup recovery.
• Local tools: Read, Write, Edit, Bash, Glob, Grep. File writing and command execution follow permission policies.
• First-run guidance: Shows different states (“configure missing connection / select default connection / select default model / start conversation”) based on actual connection status.
• Settings center: Model, account, usage statistics, daily review, local memory, voice model, open gateway, bot conversations, web search, network proxy, permissions and capabilities, health status, data, and about.
• Local memory: MEMORY.md management, manual addition, archive/restore, agent read toggle.
• Web search: Tavily credential configuration, testing, and agent tool boundaries.
• Bot entry points: Configuration/testing/running status framework for Telegram, Feishu, WeCom, WeChat iLink, Discord, DingTalk, QQ.
• Open gateway: Local HTTP/SSE API, protected by token, exposing session status, events, capabilities, and health summary to external clients.
• Office document workflow: Enabled after local officecli detection. Supports reading, validation, and per-use authorization for editing.
• Runtime kernel: AgentRun ledger, RuntimeEvent read model, ToolRuntime, ModelAdapter, RunTrace, and recovery logic.

Local and privacy boundaries

By default, Maka stores working data in the workspace directory under Electron userData:

text /workspaces/default/ llm-connections.json credentials.json settings.json sessions/

Important boundaries:

• Provider connection metadata and session JSONL are stored on the local filesystem.
• Sensitive values like API keys, OAuth tokens, bot tokens, proxy passwords, gateway tokens, Tavily keys are encrypted using Electron safeStorage before being written to credentials.json.
• The renderer never directly accesses plaintext keys; Settings only shows masked status and test results.
• File read/write, shell, and dangerous operations require permission engine approval.
• Incognito/privacy context, memory, voice, workspace instructions, and other capabilities are governed by separate contract documents.

Quick start

This repository uses npm workspaces. Although a pnpm-workspace.yaml exists, current scripts and lockfile use npm.

sh npm install npm run dev

npm run dev will first build all workspaces, then start the Electron desktop app.

If you set ELECTRON_SKIP_BINARY_DOWNLOAD=1 when installing dependencies, you need to install the Electron platform binary before starting:

sh node node_modules/electron/install.js

Common development commands:

sh npm run build npm run typecheck npm --workspace @maka/desktop run test npm --workspace @maka/runtime run test npm --workspace @maka/core run test

For desktop visual and real window verification:

sh npm --workspace @maka/desktop run screenshots npm --workspace @maka/desktop run screenshots:diff:stable npm --workspace @maka/desktop run smoke:real-window

Pre-release basic checks:

sh npm run check:release

Optional environment variables

These variables only affect local development or specific capabilities:

Project structure

text apps/desktop/ src/main/ Electron main process, IPC, settings, OAuth, bot, gateway src/preload/ window.maka preload bridge src/renderer/ React desktop UI and Settings surfaces packages/core/ Pure contracts: sessions, events, settings, permissions, model connections packages/storage/ File-backed session, settings, connection, run-ledger stores packages/runtime/ SessionManager, AgentRun, AI SDK runtime, tools, bots, telemetry packages/ui/ Shared rendering components, markdown, artifacts, redaction helpers docs/ Product, runtime, design-system, privacy and test-plan contracts scripts/ Build hygiene, screenshot, smoke and release helpers

Runtime architecture

The current runtime has been restructured from a single large flow into clearer kernel boundaries:

text SessionManager -> AgentRun -> AiSdkBackend -> ModelAdapter -> ToolRuntime -> RunTrace -> AgentRunStore

Key principles:

• SessionManager remains the public runtime API exposed to desktop, bot, and gateway.
• AgentRun is responsible for the durable run fact of a single turn and startup recovery.
• ToolRuntime handles tool input validation, permissions, watchdog, abort, telemetry, artifact candidates, and error classification.
• ModelAdapter isolates provider stream/error/usage normalization.
• RunTrace is best-effort; trace write failures must not affect user conversations.

For more details, see:

• docs/runtime-kernel.md
• docs/runtime-v2-architecture-evolution.md
• docs/runtime-v2-implementation-notes.md

UI and product quality contracts

Maka’s UI is not casually assembled pages. There is already a dedicated design system and test plan:

• docs/design-system.md: Color, density, states, motion, Settings IA, copy, and a11y contracts.
• docs/ui-quality-plan.md: Real window, visual screenshots, interaction states, regression verification strategies.
• docs/full-product-test-plan.md: Full QA route from first run, settings, sessions, tools, search, bots, gateway to failure paths.

When changing UI, don’t just run TypeScript. At minimum, accompany with:

1. Node:test contracts for the corresponding surface.
2. Passing check-console / check-a11y.
3. Supplementing visual fixtures or real window smoke tests when necessary.

Pre-contribution checks

For routine code changes, it is recommended to run at least:

sh npm run typecheck --workspaces --if-present npm run build git diff --check

For changes involving desktop renderer / Settings / IPC, also run the corresponding focused suite, for example:

sh npm --workspace @maka/desktop run test -- settings-form-a11y-contract visible-copy-hygiene-contract

For changes involving runtime / storage, also run the corresponding workspace tests:

sh npm --workspace @maka/runtime run test npm --workspace @maka/storage run test

Related documents

• CHANGELOG.md: Summary of currently unreleased changes.
• SECURITY.md: Security boundaries and reporting methods.
• docs/workspace-privacy-context.md: Workspace privacy context.
• docs/search-service-threat-model.md: Search service threat model.
• docs/memory-threat-model.md: Local memory threat model.
• docs/voice-threat-model.md: Voice capability boundaries.
• docs/maka-capability-audit-v1.md: Capability maturity audit and subsequent roadmap.