Digital Secretary
Allows zero-footprint management of Docker containers over SSH, including telemetry, logs, restart and stop controls, and declarative configuration deployment with rollback.
Provides tools for inspecting commits, merge requests, branches, and CI/CD pipelines on self-hosted or cloud GitLab, verifying deployment targets, and triggering zero-downtime production deployments with health verification.
Integrates with Gmail via OAuth 2.0 to read inbox messages, send emails, and create drafts, with human-in-the-loop approval for outgoing communications.
Integrates with Google Calendar via OAuth 2.0 to list events and create calendar entries, with approval gating for sensitive actions.
Manages Linux systemd services and host telemetry over SSH, including resource usage, journalctl logs, service state changes, and configuration deployment with health-check rollback.
Provides Odoo database schema and module inspection as part of migration analysis and upgrade rehearsal workflows.
Allows zero-footprint management of Podman containers over SSH, including telemetry, logs, restart and stop controls, and declarative configuration deployment with rollback.
Enables deep PostgreSQL schema inspection, database overviews, module and table inspection, and database-to-database comparisons for migration risk assessment.
Provides a Telegram assistant and Telethon-based personal MTProto client tools for searching chats, reading incoming messages, and sending direct messages under approval gating.
VPS-MCP & Digital Secretary
An enterprise-grade Model Context Protocol (MCP) platform and autonomous Executive Digital Secretary that bridges AI models (Claude, Groq, DeepSeek, Qwen, Nemotron) with real-world infrastructure, enterprise databases, Git workflows, knowledge libraries, and personal productivity channels.
The system runs locally on your machine, communicating over secure SSH to remote servers without requiring persistent background daemons on target hosts.
Core Platform Pillars
Executive Web Cockpit & Telegram Assistant (
assistant): A local dark-mode command center (http://127.0.0.1:8765) and always-on Telegram bot with multi-model routing (Groq, DeepSeek, local Qwen via LM Studio, Nemotron), multi-step tool execution loops, GFM Markdown tables, and human-in-the-loop action approval guardrails for sensitive actions.Remote Infrastructure & Services (16 tools): Zero-footprint management of systemd services and Docker/Podman containers over SSH. Features live telemetry, journalctl log inspection, restart/stop/boot controls, and declarative configuration deployment with syntax diff previews and automatic rollback on health-check failure.
Database & Migration Rehearsal (13 tools): Deep PostgreSQL and Odoo schema inspection, database-to-database diffing with automated risk verdict generation (
safe_to_promote,review_warnings,do_not_promote), and deterministic upgrade rehearsals on disposable copy databases.GitLab CI/CD & Production Deployments (15 tools): Direct integration with self-hosted or cloud GitLab instances. Inspect commits, merge requests, branches, and pipeline jobs; verify deployment targets; and trigger zero-downtime ref rollouts to production with automatic health verification.
Knowledge Base Dense Semantic RAG (6 tools): Dedicated vector library for indexing technical books (e.g. Designing Data-Intensive Applications), research papers, and documents using FAISS and SentenceTransformers (
all-MiniLM-L6-v2) with page-level citations. Completely isolated from operator profile memory.Google Workspace Integration (8 tools): OAuth 2.0 integration for Google Calendar (
calendar__events,calendar__create) and Gmail (email__inbox,email__send,email__draft), with interactive phone and desktop approval gating for outgoing communications.Personal Telegram MTProto Client (5 tools): Telethon-powered user client integration for searching personal chats, reading incoming messages, and sending direct messages under approval gating.
Shared Agent Memory (
agent-memory, 5 tools): Cross-client and cross-project knowledge store holding facts, architectural decisions, procedures, and operator profiles with confidence scores, provenance tracking, and expiration policies.Modular Lazy Tool Catalog (90+ Tools): Over 90 tools organized into modular toolsets (
services,db,migration,gitlab,jobs,files,kb,calendar,email,memory,telegram) to keep prompt token counts minimal and prevent LLM rate-limiting.
What It Gives Your Agent
Structured JSON Answers instead of Fragile Shell Sessions: "Is Odoo healthy?" is a single, typed tool call returning compact telemetry, eliminating raw SSH shell scraping and keeping token usage minimal for smaller models.
Guaranteed Safety & Human-in-the-Loop Approvals: Sensitive write operations (service restart, file modification, database copy drops, outgoing emails) pause for explicit confirmation via the phone messenger or Web Cockpit.
Zero-Footprint Server Architecture: Nothing runs permanently on target servers. Only an SSH key, a dedicated unprivileged user, and a minimal sudoers profile are required.
Deterministic Upgrade Confidence: Run full migration rehearsal pipelines on isolated clone databases before touching production data.
Multi-Model Flexibility: Switch models on the fly between lightning-fast cloud APIs (Groq
gpt-oss-120b, DeepSeek) and completely private offline local weights (Qwen 2.5 via LM Studio).
Design documents: specs/001-vps-service-mcp/ (services),
specs/002-odoo-migration-analysis/ (migration),
specs/003-declared-jobs/ (jobs),
specs/004-agent-memory/ (memory),
specs/005-gitlab-integration/ (GitLab),
specs/007-assistant-runtime/ (personal assistant),
specs/008-lazy-tool-loading/ (lazy tool loading),
specs/009-knows-me/ (operator profile & recall),
specs/010-web-and-media/ (web, photos, documents),
specs/011-email-and-calendar/ (Google Workspace),
specs/012-personal-telegram/ (personal Telegram account MTProto), and
specs/013-knowledge-base-rag/ (knowledge base RAG).
Contents
Related MCP server: NostrPulseMCP
The 90+ Tool Ecosystem
The platform exposes over 90 specialized tools divided across VPS/GitLab MCP services and Digital Secretary built-ins, orchestrated with token-saving lazy loading:
Domain | Tools | Primary Tools | Capabilities |
VPS Infrastructure & Systemd | 16 |
| CPU/RAM/Disk metrics, journalctl logs, state mutation, declarative config rollback |
PostgreSQL & Odoo DBs | 5 |
| Schema introspection, installed modules, table row counts, live database comparisons |
Migration Rehearsals | 8 |
| Automated upgrade pipelines on disposable copy databases, finding analysis, risk verdicts |
GitLab CI/CD & Deploy | 15 |
| Inspect repos, branches, MRs, CI jobs, verify targets, zero-downtime production deployments |
Declared Background Jobs | 4 |
| Script integrity verification, background execution tracking, automated final reports |
Knowledge Base Semantic RAG | 6 |
| Dense vector search across technical books (DDIA) and PDFs with exact page-level citations |
Local Machine Filesystem | 8 |
| Safe local file management with directory traversal protection and size caps |
Google Workspace | 8 |
| Calendar agenda tracking, meeting links, unread emails, and gated draft sending |
Personal Telegram MTProto | 5 |
| Search personal dialogs, read incoming messages, interact under confirmation gating |
Persistent Agent Memory | 8 |
| Cross-agent facts, procedures, decay policies, operator profile cards ("Knows Me") |
Background Cadences & Web | 7 |
| Cron routines, automated morning briefings, live web research with domain filtering |
Requirements
Where | What |
Laptop | Python ≥ 3.12, uv, an MCP client |
VPS | Linux with systemd (≥ 248 recommended: Ubuntu 22.04+, Debian 12+, RHEL 9+), apt or dnf, SSH; optionally Docker or Podman |
Migration tools | PostgreSQL ≥ 14 on the VPS (for the |
Quick start
git clone https://github.com/navid72m/vps-mcp && cd vps-mcp
uv sync1. Create a dedicated SSH key and VPS user. Run the ssh root@… part with any account that
already has root on the VPS.
ssh-keygen -t ed25519 -N "" -f ~/.ssh/vps_mcp_ed25519
ssh root@<vps> "useradd -m -s /bin/bash vpsmcp && passwd -l vpsmcp && \
install -d -m 700 -o vpsmcp -g vpsmcp /home/vpsmcp/.ssh && \
echo 'restrict,pty $(cat ~/.ssh/vps_mcp_ed25519.pub)' > /home/vpsmcp/.ssh/authorized_keys && \
chown vpsmcp: /home/vpsmcp/.ssh/authorized_keys && chmod 600 /home/vpsmcp/.ssh/authorized_keys"2. Install the least-privilege sudoers profile. Review the generated file first.
uv run vps-mcp bootstrap --print-sudoers --runtime docker --pm apt > vps-mcp.sudoers
scp vps-mcp.sudoers root@<vps>:/tmp/
ssh root@<vps> "visudo -cf /tmp/vps-mcp.sudoers && install -m 0440 /tmp/vps-mcp.sudoers /etc/sudoers.d/vps-mcp"3. Pin the VPS host key. Compare the printed fingerprint with one you already trust, for
example from ssh-keygen -lF <vps>.
mkdir -p ~/.config/vps-mcp
uv run vps-mcp trust-host --host <vps> --known-hosts ~/.config/vps-mcp/known_hosts4. Write the policy file. Start in read-only mode.
cp examples/vps-mcp.toml ~/.config/vps-mcp/myvps.toml # set host, key, services; read_only = true
uv run vps-mcp check-config --config ~/.config/vps-mcp/myvps.toml5. Connect your MCP client (next section). Once you trust it, set read_only = false.
check-config also prints where the memory folder will be. It's created the first time a
client starts the server.
Connect your MCP client
The server is a stdio program. Clients start it on demand and stop it when they're done, so
seeing no vps-mcp process between sessions is normal. Use absolute paths, because GUI apps
don't inherit your shell PATH.
Claude Code (available in every new session):
claude mcp add --scope user vps -- "$(which uv)" run --directory "$PWD" \
vps-mcp serve --config ~/.config/vps-mcp/myvps.tomlOptionally, let the read-only tools run without approval prompts. Add this to
~/.claude/settings.json under permissions.allow:
"mcp__vps__list_services", "mcp__vps__get_service_status", "mcp__vps__get_service_logs",
"mcp__vps__get_resource_usage", "mcp__vps__get_service_config", "mcp__vps__get_audit_log",
"mcp__vps__list_revisions",
"mcp__vps__db_list", "mcp__vps__db_overview", "mcp__vps__db_modules", "mcp__vps__db_table",
"mcp__vps__db_compare", "mcp__vps__get_report", "mcp__vps__list_reports",
"mcp__vps__rehearsal_status", "mcp__vps__pipeline_last_run",
"mcp__vps__list_jobs", "mcp__vps__job_status",
"mcp__vps__memory_search", "mcp__vps__memory_get",
"mcp__vps__gitlab_projects", "mcp__vps__gitlab_refs", "mcp__vps__gitlab_tree",
"mcp__vps__gitlab_file", "mcp__vps__gitlab_commits", "mcp__vps__gitlab_compare",
"mcp__vps__gitlab_list_items", "mcp__vps__gitlab_read_item", "mcp__vps__gitlab_pipelines",
"mcp__vps__gitlab_job_log", "mcp__vps__deploy_targets"The migration and job lines only apply if you enabled those features.
Keep the state-changing tools on "ask".
LM Studio (~/.lmstudio/mcp.json) or Claude Desktop
(~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"vps": {
"command": "/absolute/path/to/uv",
"args": ["run", "--directory", "/absolute/path/to/vps-mcp",
"vps-mcp", "serve", "--config", "/absolute/path/to/.config/vps-mcp/myvps.toml"]
}
}
}In LM Studio, turn on mcp/vps in the chat's Program panel, and pick a model with
tool-calling support.
OpenCode (~/.config/opencode/opencode.json, or opencode.json in a project):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vps": {
"type": "local",
"command": ["/absolute/path/to/uv", "run", "--directory", "/absolute/path/to/vps-mcp",
"vps-mcp", "serve", "--config", "/absolute/path/to/.config/vps-mcp/myvps.toml"],
"enabled": true
}
}
}Every client that uses the same --config shares the same memory, so a note written
in one client can be found by the next session in all of them.
Using it
Ask in plain language. The assistant picks the tools.
The full set of examples, covering every tool, is in docs/USAGE_EXAMPLES.md.
"What's running on my VPS?"
"Show the last 100 lines of odoo19's logs containing 'error'"
"Which service uses the most memory?"
"Restart worker", or for a protected service, "restart nginx, I confirm"
"Deploy redis:7 as a container named cache", which shows a preview first and asks you to confirm
"Update api to ghcr.io/myorg/api:1.2", which rolls back automatically if it comes up unhealthy
"Compare db_before with db_after and tell me if it's safe to promote" (migration tools)
"Plan the full-rehearsal job", then "start it", then later "how is the rehearsal going?" (jobs)
"Where are we with the migration?" in a brand-new session, answered from memory
"Remember as a decision: promote only when the verdict is safe_to_promote" (memory)
"What changed in the addons since v1.4? Did the pipeline pass? Then deploy v1.5" (GitLab)
"Open an issue in addons with the blocking findings of the last rehearsal" (GitLab)
"Show the audit log"
Service tools
Purpose | Tools |
Look |
|
Control |
|
Lifecycle |
|
Previews: deploy, update, configure, rollback and remove return a preview unless
confirm=true.Rollback: changes are health-gated and roll back automatically on failure.
Compact output: results are compact JSON, and logs are returned as plain
YYYY-MM-DD HH:MM:SS messagelines to keep token usage low.
The full contract is in
specs/001-vps-service-mcp/contracts/mcp-tools.md.
Deploying your own code
The server deploys images and packages from approved sources. It never uploads or builds code on the VPS. To ship your code:
Build an image, ideally in CI (e.g. GitHub Actions).
Push it to a registry.
Add the registry prefix to
approved_sources.image_prefixes.Ask the assistant to deploy or update that image.
Example: Odoo with PostgreSQL
Containers that share a networks entry reach each other by service name, so the database never
needs a published port:
deploy_service name="odoo-db" kind="container" confirm=true
container={ image:"postgres:16", networks:["odoo-net"],
env:{POSTGRES_USER:"odoo", POSTGRES_PASSWORD:"…", POSTGRES_DB:"postgres"},
volumes:["odoo-db-data:/var/lib/postgresql/data"] }
deploy_service name="odoo" kind="container" confirm=true
container={ image:"odoo:18", networks:["odoo-net"], ports:["8069:8069"],
env:{HOST:"odoo-db", USER:"odoo", PASSWORD:"…"},
volumes:["odoo-data:/var/lib/odoo"] }This requires docker.io/library/ in approved_sources.image_prefixes. Networks the server
creates are removed automatically once no managed container uses them.
Docker Compose stacks: restarting them and reading their logs through the server is fine, but change their configuration or version with
docker compose.configure_serviceandupdate_servicerecreate the container from their own spec, which would detach it from Compose.
Migration analysis (optional)
Add a [migration] section to the policy file to enable 13 more tools. They're designed for
an Odoo version upgrade (e.g. 17 → 19) where upgrade dumps and test databases live on the VPS
and production lives elsewhere.
Purpose | Tools |
Understand |
|
Compare + risk |
|
Rehearse on a disposable copy |
|
Your own runs and checks |
|
Cleanup |
|
Comparison. db_compare snapshots both databases. Each difference becomes a finding,
classified blocking / warning / info:
Schema: tables and columns removed or added, type narrowing and widening, and constraints and indexes.
Rows: row losses. The largest tables are always counted exactly, because statistics can be stale after an upgrade.
Odoo state: modules not upgraded or stuck in "to upgrade", and deactivated or orphaned views.
The report ends with a verdict: safe_to_promote, review_warnings or do_not_promote.
Rehearsal. rehearse without confirm returns a plan: the copy name, each step with a
fingerprint of its file, and free disk before and after. Confirming with the plan's plan_hash:
creates an HMAC-marked copy of the source;
runs your declared steps (SQL files, scripts,
odoo-bin -u all, re-upgrade of stale modules) against the copy only, in a background systemd unit that keeps running if your client disconnects;produces a source-vs-copy report.
Copies expire after copy_retention_h (default 24 h).
Setup on the VPS (as root, after reviewing each output):
uv run vps-mcp bootstrap --print-sudoers --with-migration --config ~/.config/vps-mcp/myvps.toml
uv run vps-mcp bootstrap --print-migration-sql | ssh root@<vps> "sudo -u postgres psql -p <port>"
ssh root@<vps> "setfacl -m u:vpsmcp:rx /opt/odoo" # lets the module-code check list addonsThe [migration] schema (targets, Odoo profile, pipelines, checks, thresholds) is documented in
contracts/migration-config.md
and in the commented section of examples/vps-mcp.toml.
How it stays safe:
Analysis runs as a database role with
pg_read_all_dataonly, in read-only sessions. Queries come from a fixed catalogue, and no tool accepts SQL.SQL step files are scanned before a rehearsal. Anything that could reach another database, the cluster, the filesystem or a shell is refused (
\c,\!,dblink,DROP DATABASE,GRANT,pg_read_file, dynamic SQL inDOblocks, …).Script steps are detected, not confined. Write counters on every other allowlisted database are checked around each step, and a write aborts the rehearsal with a blocking finding.
Copies can only be dropped if both the local record and the database's HMAC marker match.
Disk: a rehearsal needs about 1.3× the source size free plus
max(min_free_gb, min_free_pct%). It is refused up front otherwise.
Declared jobs (optional)
Some long scripts can't be rehearsed on a copy, for example a full rehearsal that drops and
rebuilds a test database from a dump, runs the deploy script, then compares the result. You can
declare such a script as a job under [[migration.job]]. Four tools then let the assistant
run it safely: list_jobs, run_job, job_status and cancel_job.
[[migration.job]]
name = "full-rehearsal"
script = "/root/full_rehearsal.sh" # root-owned, not group/other-writable
progress_file = "/root/rehearsal_logs/STEPS.txt"
report_file = "/root/rehearsal_logs/compare.md"
may_modify = ["shop_19_test"] # may be dropped and rebuilt
services = ["odoo-test"] # may be stopped
source = "shop_17_dump" # compared with result at the end
result = "shop_19_test"How a job runs:
Plan:
run_jobwithoutconfirmshows a plan: the script's fingerprint, owner and mode; which databases it will rebuild and which services it may stop; parameters; and free disk. Nothing runs yet.Run: confirming with the plan's
plan_idre-checks everything, then starts the script as-is in a transient systemd unit. The job has a runtime cap, and if it's cancelled its whole process tree is killed. It keeps running if your client disconnects. Only one job or rehearsal runs at a time.Status:
job_statusreads the job's progress file. It only reads lines written since this run started, because many scripts append to the same file across runs. It recognises outcomes such asEXIT n,rc=n,ok,FAILED,STOP…, and the success marker (ALL DONEby default).Guard: writes to any database the job doesn't declare, an undeclared database disappearing, or a change to any undeclared managed service are all reported as blocking findings.
Report: when the job ends, one report combines its step outcomes, an excerpt of its own report file and a
db_compareofsourceagainstresult, and gives a verdict.
Parameters are declared with a name and a validation pattern, and are passed only as
environment variables. For example, RUN_NAME must match ^[a-z0-9_]{1,40}$ and defaults to
rehearsal_{date:%Y%m%d_%H%M}.
Limits:
Not confined. A job is your own script running as root. The server controls what may start and when, and detects undeclared changes; it doesn't prevent them.
Cancel has limits. Cancelling stops the job's process tree, but not work it handed to other services. For example, a query already running in PostgreSQL, or a
docker execinside a container.
Optional keys:
run_as: defaults toroot.log_globsmin_free_gb: defaults to 5.max_runtime_h: defaults to 24, at most 168.success_markeroutcome_patterns: regexes withstep/statusgroups, for progress lines the built-in rules don't recognise.
All of them are commented in examples/vps-mcp.toml. The full schema
is in contracts/job-config.md, and the
tools are in contracts/job-tools.md.
Setup on the VPS: regenerate and reinstall the sudoers file with jobs enabled. This adds
stat, used for the script owner/mode check.
uv run vps-mcp bootstrap --print-sudoers --with-migration --with-jobs \
--config ~/.config/vps-mcp/myvps.toml > vps-mcp.sudoersGitLab (optional)
Add a [gitlab] section and the assistant can work with your GitLab, using your own token.
It only reaches the projects you allowlist, and only with the permissions you give each one.
1. Store the token in the macOS Keychain. This prompts for the token, so it never appears on a command line or in shell history:
security add-generic-password -U -s vps-mcp-gitlab -a <account> -wWhat you declare | Minimum token scope |
|
|
|
|
Prefer a project or group access token with the lowest role that works. The token can do whatever GitLab allows it to; vps-mcp only limits what assistants can do through vps-mcp.
2. Declare the projects and deploy targets in the policy file. See the commented block in
examples/vps-mcp.toml and
contracts/gitlab-config.md. Then
check that everything resolves:
uv run vps-mcp gitlab-check --config ~/.config/vps-mcp/myvps.tomlgitlab-check prints:
the token's user and scopes;
its expiry date, with a warning when that's under 14 days away;
whether each project is reachable;
what each deploy target currently has on the VPS.
It never prints the token.
Purpose | Tools | Permission |
Read |
|
|
Issues and MRs |
|
|
CI |
|
|
Deploy |
|
|
Assistants address projects by the alias you give them, never by GitLab path or ID, so
projects you didn't declare are unreachable. There is no merge tool at all. Closing issues needs
close_issues = true, and by default only covers issues vps-mcp created; they carry a
_Posted via vps-mcp_ footer. Every write previews first, needs confirm=true, is audited, and
is refused in read-only mode.
Deploying. deploy_from_gitlab without confirm returns a plan with:
the exact commit;
the version currently deployed and any files edited on the VPS since;
the files that change;
the pipeline status;
the services that will restart;
free disk space.
Confirming with the plan's plan_id deploys exactly that commit:
Your laptop downloads the commit's archive from GitLab. The VPS never contacts GitLab, and the token never leaves your laptop.
The laptop rebuilds it as a clean tar. Unsafe paths, links leaving the tree, special files and excluded paths are dropped, and ownership and modes are normalised.
The tar is streamed over SSH into a new release directory on the VPS:
/var/lib/vps-mcp/deploys/<target>/releases/<time>-<sha12>/ files + MANIFEST.sha256 + marker <destination> -> symlink to the active releaseThe symlink is switched in one step, so readers see either the old version or the new one.
The declared services are restarted and health-checked, including
health_urlif you set it. If anything is unhealthy, the previous release is switched back automatically.
Releases you didn't deploy through vps-mcp are moved aside to releases/pre-vps-mcp-<time>/,
never deleted. The last keep_releases versions are kept, and rollback_deploy switches back to
one of them. Deploys are refused:
while another deploy of the same target is running;
while a declared job that uses the same services is running;
while a rehearsal is running.
The deployed version of each target, and recent GitLab activity, appear in the memory, as facts that are kept up to date.
VPS setup (as root, after reviewing the output):
uv run vps-mcp bootstrap --print-sudoers --with-gitlab > gitlab.sudoers # tar, ln, mv, rm, ...Add the result to /etc/sudoers.d/vps-mcp. These binaries are root-equivalent. As with the
rest of vps-mcp, the guarantee is that the server only issues its own validated commands, on
paths under /var/lib/vps-mcp/deploys and the destinations you declared.
Memory
Memory is agent-memory, a managed knowledge store rather than a conversation log. It ships in
this repo as its own package and command (agent-memory). Every agent and every project can
share it. vps-mcp uses it as a library.
What a memory is. One concise piece of knowledge, stored as one Markdown file with structured front matter:
Field | Meaning |
|
|
|
|
| a dotted key such as |
provenance | the source ( |
|
|
lifecycle |
|
The write policy is enforced by code on every save, not left to the agent:
Secrets are refused and never written. Store a reference to where a secret lives instead.
Duplicates (same subject, nearly the same text) become a confirmation of the existing memory, not a second copy.
Contradictions on the same subject are kept on both sides, linked, and flagged
needs verification. Decisions are only replaced by an explicitsupersedewith a reason, so nothing is overwritten silently.Text from untrusted sources (READMEs, issues, web pages, tool output) is stored as
unverified. If it reads like an instruction ("ignore previous…", "always run curl …") it is refused as a procedure or decision. Only the operator can save such text, withagent-memory save --operator. Agents cannot raise trust through the tools.Facts about live state (for example "web is running") always come back with a "verify live" flag, and a "possibly stale" flag once they are older than their freshness window.
Retrieval is task-aware. When a session connects it gets only a small pinned core
(~500 tokens): pinned procedures and decisions, plus open issues. Everything else is searched
for. memory_search ranks matches by keyword relevance, recency, importance, confidence and
scope (task > environment > project > user). It returns at most 8 by default, grouped as facts,
decisions, experiences and procedures, and says "nothing relevant" instead of padding. Superseded,
expired and invalidated memories stay out of results unless you ask for history.
Tool | What it does |
| Ranked, scope-aware search, grouped by type, with flags (verify live, stale, conflict, inferred, open) |
| One memory with full provenance: history, what it superseded, conflicts, related memories |
| A validated save: created, confirmed (duplicate) or conflict (flagged) |
|
|
| Forget a memory. It previews first and moves the file to |
vps-mcp's own facts. vps-mcp writes generated, live-state facts into
environment:<vps name>: service states, the deployed version per GitLab target, the last
outcome of each job and rehearsal, and the latest report verdict. They are updated in place,
never duplicated. Agents can search them like any other memory. If the store can't be opened,
vps-mcp keeps working and says memory is unavailable.
The store. By default it lives in ~/.local/share/agent-memory/ (or $AGENT_MEMORY_HOME):
agent-memory/
├── memories/<scope>/ one .md file per memory: read, edit or delete by hand; noticed on next search
├── archive/ archived memories
├── events/ append-only history and audit (no memory content)
└── index.sqlite search index (SQLite FTS5), rebuilt from the files automaticallyUse it from any agent, not only through vps-mcp:
claude mcp add --scope user memory -- "$(which uv)" run --directory "$PWD" \
agent-memory serve --project my-project --client claude-codeThe same works in OpenCode, Antigravity or LM Studio (agent-memory serve --project …). Each
session sees its project's memories plus user scope, and never other projects' memories.
Operator commands:
uv run agent-memory search "database backup" --project my-project
uv run agent-memory save --operator --type procedural --scope project:my-project \
--subject deploy.order --title "Stop the app first" --content "…" --pinned
uv run agent-memory doctor # counts, malformed files, conflicts, stale facts, warnings
uv run agent-memory bench # recall / precision / stale hits / conflicts / token cost
uv run agent-memory migrate-004 ~/.config/vps-mcp/myvps.memory --project vps-myvps \
--environment myvps # dry run; add --apply to import feature-004 notesBenchmark (built-in fixtures: 289 memories, 22 tasks). Compared with plain keyword search, ranked retrieval keeps recall and never returns an outdated memory:
Configuration | Recall@8 | Precision@8 | Stale hits | Conflicts flagged | Tokens per result |
naive keyword search | 0.95 | 0.36 | 100% | 0% | 25 |
agent-memory | 0.97 | 0.80 | 0% | 100% | 208 |
The pinned core costs about 150 tokens.
Personal assistant
assistant is a background process that is its own agent. It runs on your laptop and talks
to you through a Telegram bot. It thinks with a language model (Claude, or a local model via LM Studio or Ollama,
or anything else with an OpenAI-compatible API), uses MCP servers such as vps-mcp as its tools, and shares agent-memory with your
other clients.
Where it runs. On your laptop, as a launchd user agent: it starts at login and is restarted
after a crash. It only makes outgoing connections (Telegram long polling, the model API, the MCP
servers), so there's no open port, domain or webhook. While the laptop sleeps it is offline. When
it wakes it sends one "missed" note instead of replaying schedules. Moving it to an always-on box
later only needs a different service definition (--systemd-user) and secrets provider (file).
Setup.
In Telegram, ask @BotFather for a bot token (
/newbot), and @userinfobot for your user id.Store the secrets in the Keychain. Run these in your own Terminal; each one prompts, so nothing is echoed:
security add-generic-password -U -s vps-mcp-assistant -a telegram_bot_token -w security add-generic-password -U -s vps-mcp-assistant -a anthropic_api_key -wThe second one is only needed for Claude. A local model needs no key: set
[model] provider = "openai"andbase_url = "http://localhost:1234/v1"(LM Studio's server) as shown in the example config. Tool use needs a model that is good at it: small models (4B to 8B) work for simple lookups but get multi-step tasks wrong more often.Several models.
[model]is the default; add[models.<name>]for others (see the example config). On the phone,/modellists them with a button each,/model geminiswitches at once, and "switch to gemini" makes the assistant send a confirm button (it never switches on its own, so text in a tool result can't move your chats to a cloud model). The choice survives restarts. Only the default model's key is needed at startup; a missing key for another model is reported when you switch.Copy
examples/assistant.tomlto~/.config/assistant/assistant.toml. Setallowed_user_ids,timezoneand the vps server'scommand.Check and install:
uv run assistant check uv run assistant service installStatus is
assistant service status; logs are in~/.local/state/assistant/logs/.
Using it. Write to the bot. Only your account gets answers: messages from anyone else are dropped before any model or tool call, and audited.
Command | What it does |
any text | Ask or instruct. It uses read-only tools directly and asks before anything else |
| Start fresh / end the conversation, and get memory proposals to Save or Discard |
| Servers, schedules, pending approvals, heartbeat · today's tokens, calls and cost |
| Recurring prompts, e.g. a morning briefing; also |
| Kill switch: cancels running work and voids approvals; nothing runs until |
| Delete stored conversation history (memory is not affected) |
| List the models (with switch buttons) or switch to one |
| Core tools, toolsets, which are loaded now, and the size of the tool list |
| What it knows about you, with edit/remove buttons · including sensitive facts · as a file |
| Getting-to-know-you questions; |
| Upcoming Google Calendar events and meetings |
| Unread emails from Gmail with sender, date, and summary snippets |
| Personal Telegram inbox, recent chats, or search messages |
| Knowledge Base: search passages, list indexed books/papers, or ingest files |
| Explore files on the laptop, inspect content, or send files to chat |
a photo, document or link | Looks at it and answers (see Web, photos and documents) |
Approvals. Each tool has a policy: auto, ask or never. By default read-only tools are
auto and everything else is ask; tools that aren't allowlisted are never offered to the
model. For an ask tool you get a message showing the tool, its arguments and the tool's own
preview (vps-mcp's confirm=false plan), with Approve / Reject buttons.
An approval is bound to that exact call, works once, and expires (10 min by default).
Buttons are signed with a key that changes on every restart, so old or forged buttons do nothing.
Scheduled runs always ask before a state-changing action, whatever the policy.
Knowing you. The assistant keeps a profile of you and the people in your life, and notes on your recent conversations, in the local agent-memory store:
"Remember …" (also "note that", "merk dir", "یادت باشه") saves the fact right away. The bot itself confirms it ("📝 Saved: …") with an ↩️ Undo button that works for 24 hours. Correcting a known fact ("actually Sara moved to Munich") replaces it and shows what it was. Only your own message can do this: text from a tool, file, web page or memory can at most become a suggestion, and passwords, PINs and keys are never stored.
Your profile (identity, work, people, interests, routines) is in every conversation, so it knows your name and your sister's city without searching.
/meshows it with ✏️ Edit and 🗑 Remove buttons,/me allincludes sensitive facts,/me exportsends everything as a file. "Forget my address" lists the matches for you to confirm.Sensitive facts (health and medication, finances, relationships, religion, politics) are kept only when you explicitly ask, never shown in the everyday profile, and never suggested.
Recaps: when a conversation ends (
/done,/newor 30 minutes idle) it writes a short recap (topics, outcomes, open loops). The next conversation starts with the last few, so it remembers what you talked about. This uses the same model call as the suggestions below.Suggestions: things it infers are proposed at the end of a conversation with 💾 Save / 🗑 Discard and a Save all button; anything it already knows is not proposed again.
/interviewasks you one question at a time (name, place, work, people, interests, answer style) to fill the profile quickly; skip or stop any time, it resumes where it left off. A thin profile gets one offer at most once a week.Memories saved before this existed (
operator.*) are read as they are;assistant knowme migrate --applyre-files them under the new scheme.
Tools and context. Not every tool is sent to the model on every message: tool definitions alone were about 10,000 tokens per call. A few core tools are always there (memory search, schedules, service status). The rest are grouped into toolsets (gitlab, db, deploy, migration, jobs, services, files, …), and the model sees a one-line catalog of them. A toolset is loaded when:
your message matches its keywords ("why did the pipeline fail?" loads
gitlabbefore the model even starts);the model asks for it with
tools__load;the model calls one of its tools directly.
A toolset that was loaded but not used goes after 2 messages; one that was used stays until 6
messages without use. /new starts again from the core. Loading never changes a tool's policy:
ask tools still ask and never tools are never shown. Groups, core tools and keywords are set per server in the
config (core = [...], [server.toolsets.<name>], see the example). [tools] lazy = false
sends everything as before, and lazy_tools on a model overrides it for that model, so a big
hosted model can get every tool while a local one stays lean. assistant check prints the size
with and without lazy loading.
Web, photos and documents.
Web search and pages. It can search the web and read pages or PDF links, and answers with the source links. Send it a link and it reads it. Search uses Tavily by default (free plan, no card, 1,000 credits a month; one search is one credit): store its key once with
security add-generic-password -U -s vps-mcp-assistant -a tavily_api_key -w. Brave Search works too ([web] search_provider = "brave", keybrave_api_key). Without a key, reading links still works. It refuses links tolocalhost, your home network or cloud metadata addresses, including through redirects, so a page can't make it probe your network.Photos and screenshots. Send one, with or without a question; several photos sent together are one question. The image goes to the model once; later messages only see "[photo]". If the current model can't see images (
vision = falsein its config), it says so and names one that can.Documents. PDFs (with a text layer), Word
.docxand text files are read and answered about ("what does this letter want from me, and by when?"). Scanned PDFs aren't read yet — send photos of the pages instead. Files over 20 MB can't be downloaded by bots.Everything from the web, a photo or a document is untrusted data: instructions inside it are never followed, and only your caption counts as your words for "remember".
Privacy: search queries go to the search provider, pages are fetched from your laptop's IP, and photos and documents go to the model provider.
Executive Web Cockpit
In addition to Telegram, you can launch a local, dark-mode web control center:
uv run assistant ui
# or: uv run assistant web --port 8765Secretary Console: Full desktop chat with on-the-fly model switcher (
groq,deepseek,qwen,nemotron).Action Guardrail: Review pending sensitive actions (emails, service restarts, file modifications) with syntax-highlighted previews, diffs, and 1-click Approve / Reject buttons.
Agenda & Inbox: Live Google Calendar events timeline and Gmail executive inbox summaries.
Knowledge Base RAG: Search ingested books (DDIA, research papers) with exact page citations and relevance scores.
VPS Telemetry: Real-time CPU, RAM, and disk utilization, plus status for all 20 systemd services and Docker containers.
Profile & Memory ("Knows Me"): Operator identity cards, working preferences, and memory explorer.
Routines & Cadences: Pause / resume scheduled briefings, timers, and cron routines.
Google Calendar & Gmail
Connects your personal assistant to Google Workspace via standard OAuth 2.0 with minimal scopes (calendar.readonly, calendar.events, gmail.readonly, gmail.send).
Setup: Place your Google OAuth client secrets at
~/.config/assistant/google_client.json.Authorize: Run the interactive OAuth flow:
assistant google-authThe refresh token is securely stored in the macOS Keychain (
google_refresh_token).Usage:
/agendaor/agenda [today|tomorrow|week]: View upcoming calendar events with meeting links./inbox: Quick view of unread emails with sender, subject, and snippet.Agent Tools:
calendar__events,calendar__create_event,email__inbox,email__send.Safety Gating: Sending an email (
email__send) always pauses for approval, presenting a full draft preview and inline Approve / Reject buttons.
[google]
enabled = true
credentials_path = "~/.config/assistant/google_client.json"
token_secret = "google_refresh_token"
max_emails = 10
max_events = 20Personal Telegram MTProto
Integrates the assistant with your own personal Telegram account via Telethon MTProto user sessions (separate from the bot API).
Setup: Obtain your
api_idandapi_hashfrom my.telegram.org and store them in the Keychain:security add-generic-password -U -s vps-mcp-assistant -a telegram_api_id -w "<your_id>" security add-generic-password -U -s vps-mcp-assistant -a telegram_api_hash -w "<your_hash>"Authorize: Authenticate via terminal session:
assistant tg-auth(Prompts for phone number and Telegram login code; session is stored in
~/.config/assistant/telegram_user.session).Usage:
/tg unread: View unread dialogs and message counts./tg chats: List recent personal chats, groups, and channels./tg search <query>: Full-text search across your personal Telegram history.Agent Tools:
tg_user__inbox,tg_user__read,tg_user__search,tg_user__send,tg_user__save(Saved Messages).Interactive Approval: Outgoing messages (
tg_user__send) always prompt for approval on your phone showing the recipient, body preview, and inline buttons before dispatching.
[telegram_user]
enabled = true
session_path = "~/.config/assistant/telegram_user.session"
max_messages = 15Knowledge Base RAG (Books, Papers, PDFs)
A dedicated, isolated vector retrieval engine for reading and asking questions across your library of books, research papers, and technical PDFs.
Strict Memory Isolation: The Knowledge Base is completely separated from your personal memory (agent-memory). Personal operator facts remain in ~/.local/state/assistant/memory/, while large reference documents and dense vector embeddings reside exclusively in ~/.local/state/assistant/knowledge_base/.
Vector Engine: Cosine similarity powered by high-performance FAISS (
IndexFlatIP) with L2-normalized dense embeddings.Embeddings: Uses
sentence-transformers(all-MiniLM-L6-v2, 384 dimensions) running locally on CPU.Document Ingestion: Extracts text page-by-page from PDFs (
pypdf/fitz), Word.docx, Markdown, and plain text. Implements paragraph-aware chunking with customizable overlap (chunk_size=1000,chunk_overlap=200).Exact Citations & Grounding: Every retrieved chunk retains its source document, title, author, and exact page number (
page 346,chunk 329).Prompt Injection Envelope: All retrieved reference excerpts are wrapped inside
<reference_content>untrusted envelopes, protecting the model from indirect prompt injections.Terminal CLI Management:
# Ingest a book or paper assistant kb add ~/Downloads/paper.pdf --title "Attention Paper" --author "Vaswani et al." # List indexed library assistant kb list # Semantic vector search assistant kb search "multi-head self attention" --top-k 3 # Remove document and its vectors assistant kb remove "Attention Paper"Telegram Chat Usage:
/kbor/kb list: View all indexed library books with chunk counts and sizes./kb search <query>: Search passages across all literature./kb add <path>: Ingest documents directly from the chat.Natural Q&A: Ask questions naturally ("According to DDIA, what is the difference between B-trees and LSM-trees?"); the assistant automatically calls
kb__ask/kb__searchand quotes page citations.
Interactive Approval: Deleting documents (
kb__remove) requires Telegram inline button approval before vectors are wiped.
[knowledge_base]
enabled = true
storage_dir = "~/.local/state/assistant/knowledge_base"
embedding_model = "all-MiniLM-L6-v2"
chunk_size = 1000
chunk_overlap = 200
top_k = 5Limits and audit.
Per-turn and per-day caps on model calls, tool calls, tokens and estimated cost stop runaway loops, and the message says which limit was hit.
Every model call, tool call, approval, refusal, schedule run and command is audited (no message text or tool output):
assistant audit --since 1d.
Privacy.
The model provider sees your conversation and the tool results it is given. With a local model, nothing leaves the laptop except Telegram messages.
Secrets never leave the Keychain except to authenticate. Anything outgoing to Telegram is scrubbed of known secrets, including text the model writes.
Tool output and memory are given to the model as labelled, untrusted data. An instruction hidden in them can't bypass the policy or an approval, and the approval message always shows the real call.
Security model
No arbitrary commands. Every remote command is a fixed template, and every input is validated and shell-quoted.
Allowlist. Only declared services, services deployed through the server, and allowlisted databases can be touched. Anything else returns
not_permitted, without revealing whether it exists.Confirmations and protected services. Destructive actions preview first. Protected services need confirmation to stop or restart, and can never be removed.
Read-only mode refuses every state change.
Lock-out guard. The SSH service can never be stopped, disabled, changed or removed.
Strict host-key pinning. There is no trust-on-first-use, and a changed host key stops everything.
Least privilege. A dedicated VPS user with a narrow sudoers profile.
Audit trail. Every state-changing attempt (including refused, failed and timed-out ones) is recorded locally in SQLite (mode 0600). Credentials and secret-looking values (
*PASSWORD*,*TOKEN*, …) are masked in output, logs and the database.
Access to the container runtime, the package manager,
psqlas postgres andsystemd-runis root- or superuser-equivalent by nature. The guarantees above come from the server only ever issuing its own generated, validated commands, so protect the SSH key accordingly.
Configuration reference
See examples/vps-mcp.toml. Every key is commented, and unknown keys
are errors. The main sections:
Section | Purpose |
|
|
|
|
|
|
|
|
|
|
| optional; see Migration analysis |
| optional, up to 10; see Declared jobs |
| optional: |
| optional: |
Validate with vps-mcp check-config --config <file>. The local audit/state database lives in
~/.local/state/vps-mcp/<vps-name>.db.
Troubleshooting
Symptom | Cause / fix |
| The VPS host key changed. Verify it out-of-band, then |
| The key isn't in |
| Port 22 is blocked or the host is down. |
|
|
|
|
Logs return 0 lines for nginx | nginx logs to |
Tools missing in Claude Code | Start a new session after |
| Free space on the VPS, or lower |
| The jobs sudoers rule is missing. Reinstall with |
| Only one job or rehearsal runs at a time. Check |
| The error includes a fresh plan. Review it and confirm with its |
| Store the token: |
| The token expired or was revoked. Store a new one with the same command. |
| The token lacks a scope or role for that action. |
| GitLab's rate limit was hit. Retry after the given number of seconds. |
A deploy reports | A service failed its health check after the switch. The previous release is active again; the response includes the service's last log lines. |
A new session doesn't seem to know the memory | Memory is searched, not injected: ask it to "search memory for …". Only pinned items and open issues arrive at connect. |
| Run |
| You have feature-004 notes; import them with the command it prints. |
Job tools missing | No |
Development
uv run pytest # unit, contract and negative suites: no VPS needed (1,102 tests)
uv run ruff check && uv run ruff format --check && uv run mypyFakes: tests run against a simulated VPS (
tests/fakes.py) and a simulated PostgreSQL cluster (tests/fakepg.py).Planted defects: one suite plants defects and checks every one is caught with the right severity.
Negative suites: over 300 disallowed requests, each asserting that nothing was changed remotely.
Integration tests run against a disposable VM. Never use them on a production server.
tests/integration/provision.sh # creates a Multipass VM with nginx, Docker and PostgreSQL
uv run pytest -m integration --vps-config tests/integration/vps-mcp.test.tomlProject layout:
src/vps_mcp/
├── server.py # MCP tools (services) + migration/jobs/memory registration, pinned core
├── cli.py # serve | check-config | trust-host | bootstrap | gitlab-check
├── config/ # policy file models and loader
├── remote/ # SSH connection, fixed-template executor, redaction
├── backends/ # systemd + apt/dnf, docker/podman
├── core/ # guard (allowlist, confirm, audit), actions, deploy, changes, queries
├── store/ # SQLite: audit, revisions, deployed services, migration tables
├── migration/ # catalogue, snapshot/diff/risk, copies, runner, rehearsal, checks
├── jobs/ # declared jobs: integrity, params, launcher, progress, guard, report
├── memory/ # adapter onto agent-memory: generated facts, tool registration
└── gitlab/ # GitLab: Keychain token, client, access, read/items/ci, archive, deploy
src/assistant/ # personal assistant runtime (daemon, CLI, Telegram bot):
│ # config, secrets, state, telegram, providers (OpenAI/Anthropic/local),
│ # toolhub (policy + previews), approvals, memory, budget, agent loop,
│ # scheduler, commands, app, service, cli,
│ # google_auth, calendar, gmail (Google Workspace),
│ # telegram_user (Telethon MTProto personal account),
│ # knowledge_base (FAISS vector store RAG for books & papers)
src/agent_memory/ # standalone memory: model, files, index (FTS5), policy, ranking, store,
# pinned core, MCP tools/server, CLI, migrate-004, bench
specs/ # speckit spec, plan, research, contracts, tasks per featureTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Maintenance
Related MCP Connectors
AI employees that run your CRM, invoicing, email, documents, dashboards and agents
AI executive assistant: email triage, inbox, calendar, files, memory, phone and connected apps.
Agentic-AI operations platform for any business — automate sales, finance, support and back-office w
Free work board for autonomous agents: pick a task, deliver it, get a verifiable certificate.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA hiring desk for autonomous AI agents — MCP server, proof-of-work entry, machine-graded role tests.MIT
- AlicenseBqualityBmaintenanceThe Decentralized Stripe & Radar for Autonomous AI Agents10149 npm1MIT
- AlicenseAqualityBmaintenanceAutonomous M2M marketplace where AI agents discover specialist agents by skill and reputation, lock credits in escrow, and delegate tasks via Contract Net Protocol.4105 npmMIT
- AlicenseAqualityBmaintenanceAutonomous Global Disaster Intelligence Wire for AI Agents1231MIT