Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
A proactive, local-first cognitive agent that works with you like a 24/7 assistant companion.
Stram is both the runtime and the agent that uses it: a local-first cognitive agent, not a chatbot waiting for the next message. It is a human-assistant-like companion for your computer: always available, context-aware, able to collect allowed signals, understand what is happening, decide whether something matters, and take the next safe step through governed tools without needing you to start with a prompt.
The project is built around practical cognition: collectors absorb desktop, browser, file, app, channel, voice, and connector events; the stimulus layer filters and ranks those signals; Stram forms a working scene, chooses a reflex or plan, uses tools, asks before risky actions, records evidence, and remembers the useful result. The goal is simple: an agent that can notice, reason, act, recover, and improve while remaining inspectable.
This is what makes Stram different: it is not flashy automation hidden behind a prompt box. It is a local, auditable cognitive loop with security, risk management, memory, approvals, and real collectors feeding it the context it needs to work beside you 24/7.
Contributing · Security · Changelog · Roadmap · Agent Positioning · Release Runbook · Agent Guidance
Native macOS shell connected to the local Stram daemon.
Stram turns collectors, stimuli, memory, connectors, policy, and approval-gated tools into one active cognitive loop.
Stram is a proactive agent system with four jobs, like a careful assistant working beside you:
- Observe the allowed environment: collectors watch opted-in desktop, browser, file, app, voice, channel, connector, and runtime surfaces.
- Understand the signal: stimuli are redacted, deduped, rate-limited, ranked, and converted into compact context instead of dumping raw private data into prompts.
- Act through governance: Stram can answer, wait, ask, draft, monitor, run tools, call connectors, or request approval depending on risk.
- Learn from evidence: outcomes, failures, approvals, useful facts, and repeated workflows are written into durable memory and skills.
| Real-world capability | What that means in practice |
|---|---|
| Work without a prompt | Wake from a schedule, file change, channel event, browser/app signal, voice transcript, connector event, or task continuation instead of waiting for chat input. |
| Build a working scene | Combine allowed collectors into a local context: active app, browser state, files, shell output, connector events, channel messages, voice, and prior memory. |
| Decide the right posture | Respond immediately, observe quietly, ask for clarification, draft a reply, monitor a condition, queue a task, recover from failure, or request approval. |
| Use real tools | Operate browser, files, shell, code, OS surfaces, channels, voice, memory, providers, and connector-backed SaaS tools through explicit schemas. |
| Manage risk | Label tools by risk, enforce permissions, redact sensitive payloads, pause high-risk actions, keep approvals human-visible, and write an audit trail. |
| Remember useful context | Keep goals, commitments, environment facts, interaction history, outcomes, lessons, and reusable workflows across sessions. |
| Run on desktop | Use the same local backend from Windows and macOS apps for chat, runs, approvals, channels, voice, settings, model routing, and autonomy controls. |
Most assistants are prompt-first: you ask, they answer, they stop. Stram is environment-first: it can absorb signals from the work surface, decide what matters, and continue a goal over time.
- Proactive by design: Stram can wake from collectors, schedules, channel events, file changes, voice, and runtime triggers, not only direct messages.
- Collectors before action: local and connector-backed collectors create a metadata-first picture of what is happening before the model plans.
- Attention before noise: dwell, dedupe, policy, rate limits, privacy tiers, and model-led attention prevent every event from becoming an action.
- Reflexes for the fast path: approvals, interrupts, recovery, wakeups, monitoring, and proof checks can route work without losing the active goal.
- Risk managed at the tool boundary: shell, browser mutation, screenshots, external sends, destructive operations, code execution, and sensitive data flows can pause for approval.
- Memory with jobs: goals, commitments, profile facts, environment notes, lessons, interaction history, and skills are separated so Stram can recall the right thing for the right reason.
- Evidence before completion: Stram should not simply say it succeeded; runs carry traces, tool output, approvals, screenshots, logs, and verifier results where applicable.
| Scenario | What Stram can do |
|---|---|
| You step away during a build | Notice test output or CI status, summarize the failure, prepare a fix plan, and wait for approval before changing files or running risky commands. |
| A teammate messages in Slack | Treat the message as a channel stimulus, inspect relevant project context, draft a response, and require approval before sending. |
| A calendar event or meeting ends | Detect meeting artifacts or transcript availability, extract action-item metadata, create follow-up tasks, and remember commitments. |
| A browser workflow changes | Observe allowed tab/page metadata, connect it with the current goal, and decide whether to monitor, ask, or continue the task. |
| A file or document changes | Convert the event into context, update the working scene, and resume the related task if it affects an active goal. |
| A high-risk action is needed | Pause with an approval request that explains the tool, purpose, risk, and proposed arguments before execution. |
Stram is both the runtime and the agent that uses it, not two separate named things. The runtime provides the body: APIs, collectors, tools, memory, approvals, native apps, connectors, policy, and release surface. Stram's agent behavior uses that body to act like a cognitive assistant that understands the user's working environment without becoming an uncontrolled recorder.
| Agent layer | What it does |
|---|---|
| Collectors | Metadata-first collectors watch allowed desktop, browser, file, app, channel, meeting, developer, knowledge, and business surfaces. |
| Stimuli | Events become structured stimuli with source, privacy tier, confidence, timestamps, dedupe keys, and compact evidence. |
| Attention | Stram ranks stimuli by urgency, relevance, source trust, active goals, user state, and risk before deciding whether to act. |
| Reflexes | Fast paths handle wakeups, approvals, interrupts, recovery, monitoring, cancellation, and proof checks. |
| Connectors | Google Workspace, Microsoft 365, Slack, GitHub, Linear, Notion, Zoom, browsers, IDEs, CRMs, file stores, model providers, and local apps expose governed capability surfaces. |
| Memory | Goals, commitments, focus, background learning, profile facts, lessons, summaries, and skill evolution stay durable across sessions. |
| Governance | Tool schemas, risk levels, permission checks, local outbox records, approval gates, timeline evidence, and redacted traces make the agent inspectable before and after it acts. |
Most assistants are either chat-first, code-first, or automation-first. Stram is cognition-first: its agent gets a governed perception loop, a durable memory system, a real desktop body, connector-aware tools, and a safety model that treats user trust as part of the product.
| Product shape | Center of gravity | Stram difference |
|---|---|---|
| Chat assistants | Strong conversational answers after a prompt. | Stram can keep watching allowed signals, maintain goals, wake later, and decide whether to observe, ask, draft, monitor, or act. |
| Coding agents | Repo-aware code changes and tests inside a task session. | Stram includes coding workflows, but the core product is a broader active assistant with collectors, reflexes, connectors, voice/channels, memory, and governed desktop tools. |
| Automation tools | Trigger-action workflows that run when a rule matches. | Stram uses model-led attention, memory, policy, approvals, and evidence instead of only static triggers. |
| Agent runtimes | Tool calls, runs, events, approvals, and APIs. | Stram adds the always-on local stimulus loop, native desktop clients, metadata-first collectors, cognitive state, and proactive recovery paths. |
Reference checkouts under external_repos/ are useful peers, but they expose different product shapes. Hermes Agent has a strong gateway API around /v1/runs, run events, approvals, stops, and toolsets. OpenClaw has deep exec/channel approval mechanics and mobile/watch surfaces. Open Interpreter exposes simple chat/history server examples. browser-use and windows-use are focused automation libraries. screenpipe is a local activity capture/search API.
Stram's novelty is the combined loopback API: cognition, native desktop control, update delivery, channels, voice, approvals, tools, memory, browser sessions, workflows, and autonomy are all one governed runtime surface.
| Stram API | Capability exposed to apps | Not observed as a combined desktop REST surface in the local references |
|---|---|---|
| /stimuli, /stimuli/stream | Normalize user text, voice transcripts, activity, channel events, and other stimuli into one response/observe/monitor harness with live run events. | Peers usually expose chat/run entrypoints, not a stimulus API tied to attention decisions and desktop response modes. |
| /channels/* | Channel catalog, requirements, setup save, doctor, smoke test, inbound preview, listener tick, outbox, prepared sends, and approval-gated live sends. | Hermes/OpenClaw have messaging channels, but not this setup/doctor/smoke/outbox contract consumed by both native desktop apps. |
| /voice/status | Let desktop clients pass runtime STT/TTS secrets without echoing values, then show provider readiness before voice workflows. | Other refs include voice features or providers, but not this shared app-facing voice readiness API. |
| /approvals, /runs/*/timeline, /runs/*/cancel | Review pending high-risk actions, inspect evidence timelines, approve/reject/edit, and cancel active work from the same UI. | Hermes has run approvals; Stram adds the native desktop timeline/cancel/approval contract across all local tools. |
| /memory/*, /autonomous/*, /triggers/evaluate | Surface durable memory, summaries, autonomous queue state, wakeups, and trigger evaluation for ongoing cognition. | Reference APIs did not show this cognition state as a first-class desktop API. |
| /collectors/* | Configure and tick privacy-first local stimulus collectors for active window, browser context, filesystem changes, clipboard, screenshot/OCR keyframes, video keyframes, and audio activity. Sensitive capture stays opt-in; deterministic dwell, dedupe, batching, policy, and rate filters keep raw telemetry local while compact attention batches reach the harness. | Peers expose chat/gateway events, but not a shared desktop collector layer feeding a governed stimulus/attention loop. |
| /events/status, /events/rebuild-context | Convert compact collector batches and direct text/voice/channel stimuli into semantic events, generated current_context.md / events.md, and queued autonomous action candidates. | Peers expose run events, but not a privacy-first semantic event layer that turns local stimuli into durable context before autonomous action. |
| /tools, /tools/search, /tools/describe, /capabilities | Publish the active governed tool catalog, schemas, risk levels, and capability groups to the UI. | browser-use/windows-use expose tool libraries; Stram exposes a governed cross-domain catalog to native clients. |
| /browser/sessions, /screen/captures, /permissions | Inspect browser sessions, local screen evidence, and permission posture before or after tool use. | screenpipe has local capture APIs and browser-use has browser actions; this ties those surfaces into the agent approval/audit runtime. |
| /updates/latest | Existing desktop users can check the latest GitHub release and open the platform-specific download without leaving the app. | The local references checked did not expose a shared release-update endpoint for native desktop shells. |
Stram currently targets Python 3.12+.
git clone https://github.com/CodeInfinity1/Stram.git
cd Stram
python3 -m pip install -e ".[browser,pdf,ocr,office,test]"Optional browser support:
playwright install chromiumCopy the example environment file only when you need model, voice, channel, or release settings:
cp .env.example .envDo not commit .env or real secrets.
Desktop installers are published on the latest GitHub release:
- Download the Windows EXE installer
- Download the Windows ZIP archive
- Download the macOS PKG installer
- Download the macOS ZIP archive
- Verify release checksums
Package-manager metadata is checked into this repository and mirrored to dedicated package-manager repos where needed. See Package Manager Distribution for publishing and registry-submission details.
macOS with Homebrew:
brew tap CodeInfinity1/stram
brew trust CodeInfinity1/stram
brew install --cask stramWindows with WinGet local manifest:
winget install --manifest .\winget\manifests\b\CodeInfinity1\Stram\1.0.0Windows with Scoop:
scoop bucket add stram https://github.com/CodeInfinity1/scoop-stram
scoop install stramWindows with Chocolatey package source:
choco pack .\chocolatey\stram\stram.nuspec --out .
choco install stram --source . -yOfficial WinGet and Chocolatey registry availability requires external repository/review or account/API-key submission. Public production macOS installs should use a Developer ID signed and notarized package, and Windows installs should use an Authenticode-signed EXE; until those certificate flows are complete, Gatekeeper and Windows SmartScreen may warn that the publisher is unverified.
macOS Gatekeeper warning workaround: the current .pkg and .zip releases are not yet Developer ID signed/notarized, so opening them will show "Apple could not verify this app is free of malware." This is expected for this release, not a corrupted download. To install anyway:
- Try opening the .pkg normally first, then go to System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the Stram warning.
- If macOS blocks it outright with no "Open Anyway" option, clear the quarantine flag from Terminal instead:
(or on the installed .app, e.g. xattr -dr com.apple.quarantine "/Applications/Stram.app")
xattr -dr com.apple.quarantine /path/to/Stram-macOS.pkg
- Always verify the download against checksums.txt before bypassing Gatekeeper — the warning is expected, a checksum mismatch is not.
Windows SmartScreen warning workaround: the current Stram-Windows-Setup.exe and .zip releases are not yet Authenticode-signed, so running the installer will show "Windows protected your PC" / "Microsoft Defender SmartScreen prevented an unrecognized app from starting." This is expected for this release, not a corrupted download. To install anyway:
- On the SmartScreen dialog, click More info, then click Run anyway.
- If the file was blocked on download instead (no SmartScreen dialog appears when double-clicked), right-click the .exe → Properties → check Unblock at the bottom of the General tab → OK, then run it again.
- From PowerShell you can unblock the same way without the UI:
Unblock-File -Path .\Stram-Windows-Setup.exe
- Always verify the download against checksums.txt before bypassing SmartScreen — the warning is expected, a checksum mismatch is not.
Run a safe explicit tool call:
python3 -m stram run "system_status {}" --workspace . --planner explicitAsk the model-led planner to inspect the project:
python3 -m stram run "summarize this project and tell me the next best task" --workspace . --planner modelStart the local API and dashboard:
python3 -m stram serve --workspace . --port 8765Then open:
http://127.0.0.1:8765/
The native clients are optional shells around the same local runtime.
| Platform | Source | Local run |
|---|---|---|
| macOS | apps/macos | swift run --package-path apps/macos StramMac |
| Windows | apps/windows/Stram.App | Build with the .NET 8 SDK on Windows or the release workflow. |
Recommended desktop loop:
python3 -m stram serve --workspace . --port 8765
swift run --package-path apps/macos StramMacThe macOS and Windows apps share backend routes for chat, tools, channels, channel setup, channel doctors, prepared outbound messages, approvals, recent runs, runtime start/stop, release update checks, voice settings, model/provider settings, and bounded autonomy cycles.
Model planning is the preferred path for natural-language work. Offline fallback accepts explicit tool commands or JSON plans only.
Common environment variables:
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENROUTER_API_KEY=
NOUS_API_KEY=
ANTHROPIC_API_KEY=
DASHSCOPE_API_KEY=
GROQ_API_KEY=
GROQ_BASE_URL=https://api.groq.com/openai/v1
GOOGLE_API_KEY=
DEEPSEEK_API_KEY=
MISTRAL_API_KEY=
CEREBRAS_API_KEY=
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
OLLAMA_MODEL=llama3.1
XAI_API_KEY=
XAI_BASE_URL=https://api.x.ai/v1
NVIDIA_API_KEY=
HF_TOKEN=
MINIMAX_API_KEY=
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
LOCAL_LLM_BASE_URL=http://127.0.0.1:11434/v1
LOCAL_LLM_API_KEY=local
DEEPGRAM_API_KEY=
ELEVENLABS_API_KEY=
The --model-provider flag and desktop settings include OpenAI, OpenRouter, Nous, Anthropic, Groq, xAI/Grok, Gemini, DeepSeek, Mistral, Cerebras, Ollama, local OpenAI-compatible runtimes, Vercel AI Gateway, LiteLLM, NVIDIA, Hugging Face, Z.AI/GLM, Kimi/Moonshot, StepFun, MiniMax, Arcee, GMI, Xiaomi, Tencent TokenHub, OpenCode, Kilo Code, Azure, Copilot, Bedrock, Browser Use Cloud, OCI, and the external OAuth/runtime identities mirrored from OpenFlow/OpenClaw and Hermes. Native HTTP transports run directly; external process/OAuth-only runtimes are recognized and can be bridged with --model-base-url when an OpenAI-compatible endpoint is available.
The dashboard and desktop clients pass secret references or runtime secrets to the local daemon; they should not require raw keys in public source files.
Stram is built for real tools, so the safety surface is explicit.
- Model/provider output is untrusted until parsed, validated, and matched to an allowed tool.
- Retrieved files, web pages, tool output, transcripts, memories, and upstream skill text are evidence, not instructions.
- High-risk tools pause for approval by default.
- Approval edits are schema-validated and recorded on the source run.
- External-visible sends are prepared as local outbox items unless an adapter, credentials, policy, and approval are present.
- Browser mutation, file upload/download, JavaScript evaluation, screenshot capture, desktop UI actions, shell/code execution, and app launches are bounded and auditable.
- Provider errors and secrets are redacted before trace persistence.
- Open-source hygiene scans publish candidates for local state, signing material, likely secrets, and oversized files.
Read SECURITY.md before exposing channels, browser control, desktop control, or remote access.
stimulus
-> interaction harness
-> compact local context
-> model-led attention/planning
-> schema-validated tool calls
-> policy and approval gates
-> execution and audit timeline
-> memory, learning, recovery, and response synthesis
The cognition package is closer to a nervous system than a single planner: attention decides what deserves response, executive state keeps goals and commitments coherent, memory turns experience into durable context, self-review repairs behavior, and skill metabolism expands what the assistant can do without hiding new capability behind prompt-only claims.
Important source areas:
| Area | Path |
|---|---|
| Python runtime | stram/ |
| Cognition stores and loops | stram/cognition/ |
| Tool registry and implementations | stram/tools/ |
| Policy, approvals, audit, permissions | stram/safety/ |
| REST API and dashboard | stram/api.py, stram/dashboard/ |
| Prompt resources | stram/resources/prompts/ |
| Skills | skills/ |
| Desktop apps | apps/ |
| Release automation | script/ |
The hard rule: broad assistant behavior stays model-led and schema-driven. Deterministic code validates, constrains, audits, persists, packages, and executes explicit tools; it does not become a hidden keyword router for natural language.
| Goal | Start here |
|---|---|
| Understand agent behavior | Cognitive architecture |
| Understand the no-keyword-routing rule | Global agent instructions |
| Add or review a skill | Skill authoring standard |
| Build or package a release | Release checklist and release runbook |
| See planned work | Roadmap |
| Work as a coding agent in this repo | AGENTS.md |
python3 -m pip install -e ".[browser,pdf,ocr,office,test]"
python3 -m unittest discover -v
python3 script/verify_open_source_hygiene.py
python3 scripts/smoke_real_world_tasks.py --workspace .Before opening a PR, include the real behavior proof: exact commands, OS, model/provider path if relevant, observed result, and what you did not test.
Read CONTRIBUTING.md for contribution priorities, tool-vs-skill guidance, tests, and PR expectations.
The public release path is intentionally stricter than a source build.
python3 -m py_compile script/verify_open_source_hygiene.py script/verify_publication_state.py script/verify_release_readiness.py script/generate_release_report.py
python3 -m unittest discover -v
python3 script/verify_desktop_parity.py
python3 script/verify_desktop_runtime_smoke.py
python3 script/verify_package_managers.py
python3 script/verify_open_source_hygiene.py
python3 scripts/smoke_real_world_tasks.py --workspace .
python3 script/verify_release_readiness.py --require-website --release-tag v0.1.0
python3 script/generate_release_report.py --require-website --check-github-releaseStrict public release completion also requires signed/notarized macOS assets, signed Windows assets, checksums, a published GitHub release, and website download verification. See docs/RELEASE_RUNBOOK.md.
Stram 1.0.0 is the first tagged production release. The local runtime, tool contracts, skills, safety gates, desktop shells, release checks, and smoke coverage are covered by automated tests and release-readiness gates, but live provider/channel/desktop workflows still depend on the credentials and platform-specific signing you configure for your own deployment.
Use it, inspect it, improve it, but do not treat it as a silent background operator until you have reviewed the approval and channel setup for your environment.
MIT. See LICENSE.