always-accompany
One memory and context framework behind companionship, chat, coding, and work agents.
- Source repo
- beilusaiying/always-accompany
- Stars
- ★ 459
- Last updated
- 2mo ago
- License
- AGPL-3.0
- Primary language
- JavaScript
- FA score
- 37/100 · Major gaps
At a glance
- Works with
- Portable with changes
- You'll need
- Typical use
- Long-running roleplay users who want to import SillyTavern character cards, presets and worldbooks and have old material recalled automatically instead of stuffing everything into the window.
- Main limitation
- The author states most of it was built single-handedly in about three months plus roughly one month of algorithm optimization, so structure, basic features and edge-case handling may be unstable and maturity varies by module.
- Source review
- 37/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
always-accompany is a self-hosted AI + Agent project whose organizing idea is context and attention: long-term material lives in an editable structured Data table plus hot/warm/cold JSON and Markdown layers, and a self-driven P1 recall chain selects the relevant excerpts before each reply. It ships four main modes — Smart (fully autonomous), Chat/roleplay, Code (IDE-style three-panel workflow) and Work — each with its own memory tables, private directories and P1 route. The backend runs on Deno with a vanilla JavaScript/ESM frontend, organized through Shells, Plugins, Service Generators and the yonban function layer; application data is stored locally. Around that core sit MCP tool connections, user plugins writable in JS, Python or as standalone programs, a Live2D/image desktop companion with screen awareness, local MOSS-Transcribe-Diarize voice input, and bot shells for nine messaging platforms. The author states most of it was built by one person in about three months plus roughly a month of algorithm optimization, so module maturity varies and the project is explicitly still stabilizing.
The run.bat / run.sh launcher starts a Deno service and serves a web UI at http://localhost:1314; after binding an AI service URL, API key and model you can chat. Before each reply the P1 chain runs Node0–4: Node0 gathers the current input, recent user messages and current-mode Data; Node1 builds tokenization, POS, time, proper-noun and phrase anchors; Node2 expands associations from SWOW / ConceptNet / Cilin / ATOMIC and domain terms; Node3 filters with multi-evidence signals (BLQ, NB300, WordNet); Node4 returns to Data, hot/warm/cold and mode records and ranks by BM25, time, layer, Top and importance, emitting recalledRecords, directionWords and trace. In Code mode it reads and edits project files, executes commands and keeps task lists. Context usage is tracked per message, file read, tool result and system injection; default cleanup only writes a _hidden marker so the record stays on disk and can be restored, and the model can request cleanup via <contextClean>. Also included: MCP JSON configuration, six permission templates (L0–L5) with per-tool and per-path rules, Live2D/image desktop companionship with three screen-awareness modes, local voice transcription, and bot shells for Discord, Telegram, Slack, LINE, Lark/Feishu, DingTalk, WeChat, WeCom and X.
- Long-running roleplay users who want to import SillyTavern character cards, presets and worldbooks and have old material recalled automatically instead of stuffing everything into the window.
- Solo developers on a large codebase who need the agent to read call chains and Markdown notes, then drop file reads it no longer needs at file-read granularity instead of re-reading after compaction.
- People running several contexts side by side who want Chat, Code and Work to keep separate tables and private directories so a new project is not anchored to an old one's memory.
- Prompt tinkerers who want to edit character definitions, presets, INJ entries, injection role and position, and conditional trigger rules entry by entry.
- Desktop-companion users who want a Live2D or image avatar with screen awareness and proactive comments, and who accept local deployment plus their own model.
- Operators of self-built multi-platform bots who already hold Discord/Telegram/Feishu tokens or webhooks and want to reuse one memory framework.
How do you install or deploy this agent?
You need one working AI API (service URL, key and model name) plus basic prompting ability. Clone the repository and run the launcher for your platform; it downloads the Deno runtime when missing and completes installation when dependencies are incomplete:
git clone https://github.com/beilusaiying/always-accompany.git
cd always-accompany
run.bat # Windowschmod +x run.sh && ./run.sh # Linux / macOSThe first launch takes longer because it downloads runtime dependencies and initializes local data; wait for the full page before interacting. If the browser does not open, visit http://localhost:1314 manually. Optional features such as voice and the desktop companion have their own first-use downloads or environment requirements, and the self-driven P1 local retrieval service (measured peak memory on the order of ~2 GiB) can be switched off entirely.
How do you use this agent?
Pick the interface language on the onboarding screen, enter the service URL, API key and model, save, then select or import a character card to start chatting. Deeper configuration covers P1 parameters, prompt injection positions, Code and Work modes, permissions and plugins.
1. Onboarding → choose interface language
2. Bind an AI service → service URL / API key / model → save
3. Select or import a character card → start chatting
4. To change behavior → edit character definitions, presets, INJ entries, injection position and conditions
5. To change permissions → pick an L0–L5 template, then refine deny / ask / allow per tool and pathMCP tools are connected by pasting JSON; command-type servers must additionally pass owner and environment-variable allowlist gates. A Wiki ships inside the app, with an online version also available.
What are this agent's strengths and limitations?
- Memory is ordinary local JSON/Markdown plus an editable Data table and a hot/warm/cold split, so users can read and correct it directly instead of trusting an opaque vector store.
- Context cleanup works at file-read granularity and is reversible: default cleanup only sets a _hidden marker, the model can request cleanup with <contextClean>, and a minimum token threshold avoids repeatedly breaking the prompt cache.
- P1 exposes a white-box panel showing input units, per-node candidates and removal reasons, index state and final sources, so a miss can be told apart from a broken chain.
- Main prompt entries — character definitions, presets, INJ entries, mode instructions, memory data slots and tool guidance — are editable in the UI for content, order, enablement, role and injection position.
- A plugin-based architecture: 23 built-in plugin directories, user plugins in JS, Python or standalone programs, with core features routed through an intermediate relay station.
- Coding, office work and roleplay share one memory and permission model, so context does not have to be moved between separate tools.
- The author states most of it was built single-handedly in about three months plus roughly one month of algorithm optimization, so structure, basic features and edge-case handling may be unstable and maturity varies by module.
- First launch downloads the Deno runtime and dependencies and initializes local data, and the P1 local retrieval service has measured peak memory around 2 GiB — a real cost on modest machines.
- AIRP and Chat prompts are still being refined, with current focus on productivity rather than companionship polish.
- The nine platform bots are shells: each still needs its own token, webhook or third-party bridge, and voice support is transcription only with no AI voice playback.
- Optional semantic vector search (beilu-vectordb) is off by default and needs your own embedding endpoint; it is complementary to P1 rather than an alternative.
- The project has declared it will stop adding new plugins and feature areas, shifting to core reduction and a plugin protocol, so interface churn is expected.
How does this agent compare with similar options?
The README names SillyTavern as the pioneer whose character-card, preset and worldbook formats it imports, and fount as an early reference framework for message handling and module loading; it also cites OpenAI Codex and Claude Code issues as evidence of context bloat. These are reference points, not measured head-to-head comparisons, and the repository publishes no benchmark against them.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| always-accompany This agent | 37 · Major gaps | — | ★ 459 | 2mo ago | JavaScript | — |
| Remnic Agent Memory | 85 · Good | CLIFree + model costs | ★ 231 | today | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| PowerContext | 55 · Major gaps | CLIFree | ★ 1.5k | today | Python | Codex · Claude Code |
| Late | 50 · Major gaps | CLIFree + model costs | ★ 455 | 2d ago | Go | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
README asserts L0–L5 permission templates, per-tool/path deny/ask/allow, command blacklists and MCP security gates, which are claims about least privilege and user confirmation; however the only visible source is P1 test stubs, so these gates cannot be verified, hence 1 each. Data-flow transparency: README acknowledges content is sent to the chosen remote AI/embedding service but gives no field-level detail, 1. Sensitive data handling: API keys/tokens are only mentioned in setup, with no storage or encryption evidence, 1. Dependency security: package.json pins many dependencies including old fixed versions like pdf-parse 1.1.1, with no lockfile or audit evidence, 0. External effects and rollback: README mentions recycle/backup chains and reversible _hidden cleanup, but only as claims without code support, 1 each. Source attribution: README credits fount, SillyTavern and data resources, and LICENSE is full AGPL-3.0, 2.
Self-consistency: README admits a three-month build, unstable structure, uneven module maturity, and that older 21-node docs are outdated, showing doc/implementation drift, 1. Dependency availability: a very large dependency set including niche/private packages (@steve02081504/*, als-registry 0.0.0) with no lockfile, so availability cannot be statically confirmed, 1. Failure messages: visible stubs only return trace flags with no error handling or user-readable failure evidence, 0.
Audience and scenarios: README covers chat/roleplay, coding, work, desktop companion and bots with substantial scenario description, 2. Capability boundaries: it states availability depends on mode/config/model, but lists many features as 'present' with weak boundary definition, 1. Trigger precision: P1 recall and conditional injection are described but without verifiable thresholds or trigger rules, 1. Environment fit: requires Deno, optional Python services, Electron and a ~2GiB P1 service, heavy and only roughly documented, 1.
Information architecture: README is well structured with quick start, feature overview, architecture and roadmap, 2. Install notes: clone plus run.bat/run.sh with first-launch guidance, 2. Naming stability: README states structure will be refactored and features moved to a plugin layer, so naming/structure stability is doubtful, 1. Examples and FAQ: screenshots and quick start but no FAQ or runnable examples, 1. Known limitations: development note explicitly lists instability and incomplete edge cases, 2. License: full AGPL-3.0 text consistent with package.json, 2. Versioning/changelog: package.json has 1.0.3 but no CHANGELOG, 1. Maintenance responsibility: single author, unverified publisher, maintenance commitment only in roadmap prose, 1.
Output usability: only screenshots and descriptions, no actual output samples or verifiable artifacts, 1. Marginal value: clear motivation and citations for long-context memory/attention, but incremental value over existing solutions (SillyTavern, fount) is unsupported by evidence, 1. Cost-benefit: README states P1 peak memory ~2GiB and requires paid external APIs, high cost with unquantified benefit, 1.
Claim traceability: README cites issues, papers and community discussions, so some claims are traceable, but core algorithms (BLQ, NB300) have no public detail, 1. Cross-source corroboration: only README and package.json corroborate version and dependencies; functional claims lack code or test support, 1. Fact/inference separation: README distinguishes 'present' from 'direction' and admits papers do not directly prove the approach is better, which is honest, but many inferential statements remain unlabeled, 1.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- The only visible source is P1 test stubs; README security claims (permissions, rollback, MCP gates) cannot be statically verified and require independent audit before deployment.
- The dependency set is large, includes niche/private packages and pinned old versions (e.g. pdf-parse 1.1.1), and has no lockfile, posing supply-chain and availability risk.
- The project self-describes a short development cycle, unstable structure and planned refactoring, so interfaces and naming may change; not suitable for production-critical paths.
- The P1 local retrieval service peaks around ~2GiB memory and requires binding a paid external AI API; costs should be assessed in advance.
- Publisher identity is unverified by FollowAgents, and maintenance responsibility and update path are unclear.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.0 v1.0.1
Release notes excerpt
更新日志 本文件记录面向用户的发行变化。内部调查、个人路径、测试账号与密钥不进入公开更新日志。 1.0.1 — 2026-08-04 基础可用性 - 修正 AI 服务源首次保存、配置应用与重新读取链，避免已保存后仍提示未配置。 - 收紧聊天消息删除与回档后的索引传导，避免前端继续提交已经失效的位置。 - 补齐部件配置应用、生命周期取消、失败回滚与熔断边界，减少波动时的重复加载和状态假成功。 - 修正多窗口文件工作区与可信会话的绑定链，保留主窗口自动绑定和额外窗口显式绑定。 首次使用与配置 - 新用户默认提供“新的开始”角色卡，并增加语言选择与启动加载状态。 - AI 未配置时的入口改为直接引导到完整设置；子模式未绑定 API 时给出独立提示。 - 子模式默认采用严格后处理、不预填充、1,000,000 上下文和 30,000 最大输出；用户仍可修改。 P1、YonBan 与 CLI - 同步 P1 自驱动运行时、资源目录与诊断展示，补充启动波动、有限重试和宿主退出联动。 - 同步 YonBan IDE、扩展端与本体通信链，以及 CLI、文件、检查点和命令工具。 - 保留公共发布所需的 P1 资源、YonBan 和 CLI 依赖；运行时生成物与用户状态不进入仓库。 更新与数据保护 …View on GitHub ↗