Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@selfos-mcp help me set a goal to run a half marathon by May"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Turn any AI assistant into a goal coach that actually helps you follow through.
self.os is a plain-text vault your AI agents share: your goals, the habits that drive them, your reasons, your plans for when things go wrong, plus the context a good assistant needs (who you are, how you like to work, the people in your life). It ships with a CLI and an MCP server, so Claude, Cursor, OpenClaw and any MCP-capable agent can coach you from the same files, and your data never leaves your machine.
It's built around what research on goal pursuit consistently supports, rather than a to-do list:
Practice | In self.os |
Specific if-then plans ("When X, I'll do Y") | Every goal needs a |
Planning for obstacles up front |
|
Tracking measurable progress |
|
Outcomes driven by habits |
|
Regular review and re-planning | A weekly review that asks the questions worth answering |
Focus | A soft cap on active goals; agents ask what a new goal replaces |
Supportive accountability | After a miss, agents ask what got in the way and adjust the plan, never shame |
Related MCP server: big-brain
Requires Python 3.10+ and uv (or pipx). No other dependencies.
uvx --from git+https://github.com/AmineBenaceur/self.os selfos initThat creates your private vault at ~/.selfos/vault. Then connect your assistant, below,
and say "help me set a goal."
To install the selfos command permanently:
uv tool install git+https://github.com/AmineBenaceur/self.os # or: pipx install git+https://...
selfos --helpClaude Code
claude mcp add selfos -- uvx --from git+https://github.com/AmineBenaceur/self.os selfos-mcpClaude Desktop, Cursor, Windsurf, VS Code and other MCP clients. Add to the client's MCP config
(claude_desktop_config.json, .cursor/mcp.json, …):
{
"mcpServers": {
"selfos": {
"command": "uvx",
"args": ["--from", "git+https://github.com/AmineBenaceur/self.os", "selfos-mcp"]
}
}
}To use a different vault, add "env": {"SELFOS_VAULT": "/path/to/vault"}.
OpenClaw. Install selfos, then the skill in adapters/openclaw/. It drives the
same guarded actions through selfos commands, with heartbeat nudges for habits, check-ins and birthdays.
Anything else. Point the agent at AGENTS.md, or paste
adapters/generic/system-prompt.md plus selfos bundle.
Tool | Purpose |
| Preferences, identity, goals with pace, habits, birthdays. Called first |
| Creates a goal; requires an if-then plan and respects the active-goal cap |
| Logs progress (with a number if there's a metric) and returns pace |
| Pause (with a resume date), finish, re-date, add plans or obstacles |
| Habits with cues and minimum versions; log done or missed with a reason |
| Builds the weekly review and saves it to the vault |
| Remember facts about people, projects, preferences; look things up |
| Housekeeping |
It also provides the prompts set-goal, check-in, weekly-review and coach (the full protocol).
Set. The agent walks you through why, what done looks like, a metric (if any), an if-then plan, likely obstacles, and the habit that drives it.
Do. It nudges at the habit's cue and logs done or missed — <reason>.
Check in. At the goal's cadence it asks for the number and compares it to pace. When you're behind, it asks what got in the way and offers one adjustment.
Review. Weekly, it summarizes goals, habits, what's coming up, and the questions worth answering. You re-plan; it updates the files.
The full agent protocol is in AGENTS.md.
---
type: goal
title: Run a half marathon
description: Finish the Calgary half marathon in under 2:15
status: active
start_date: 2026-09-28
target_date: 2027-05-30
checkin_every_days: 7
metric: weekly distance
unit: km
baseline: 8
target: 40
updated: 2026-10-16
---
## Why
- I want proof I can commit to something hard outside work [stated]
## Plan
- When my alarm goes off Tue/Thu/Sat at 6:00, I put on the clothes I laid out and go. [stated]
## Obstacles
- If it's below -15°C, then I run on the treadmill instead. [stated]
## Log
- 2026-10-12: value=14 skipped Saturday, cold [stated]Plain Markdown: read it, edit it by hand, grep it, version it. See examples/vault/
for a complete vault, and schema/frontmatter.md for every field.
selfos init [--git] # create your vault (optionally as its own private git repo)
selfos goals [--all] # goals with pace, check-in status, linked habits
selfos habits # this week's habit progress, streaks, last miss
selfos review [--write] # weekly review; --write saves to reviews/
selfos birthdays [DAYS] # upcoming birthdays
selfos validate # check every file; warns on missing plans and too many goals
selfos index # regenerate INDEX.md
selfos bundle # whole vault as one file, for models without file access
selfos mcp # run the MCP server on stdio
# for shell-based agents (OpenClaw etc.): same guarded writes as the MCP tools, JSON output
selfos context # everything an agent needs at session start
selfos checkin "Run a half marathon" --value 14 long run felt good
selfos log-habit run-3x-week missed too cold
selfos note people/jane-doe "Loves bouldering"
selfos tool create_goal '{"title": "...", "plan": ["When ..., I will ..."], ...}' # any MCP tool
selfos tool --list
selfos --vault examples/vault review # try it on the demo data (from a clone)From a clone without installing, use python tools/selfos.py <command>.
self.os/ ← this repo (public framework)
├── AGENTS.md ← the contract every agent follows
├── llms.txt ← map of the repo for AI agents
├── selfos/ ← CLI + MCP server (stdlib only)
├── template/ ← starter vault copied by `init`
├── examples/vault/ ← a fictional filled-in vault
├── schema/ ← frontmatter field reference
├── adapters/ ← OpenClaw skill, Claude, generic prompt
└── tests/
~/.selfos/vault/ ← YOUR data (or <clone>/vault, git-ignored, or $SELFOS_VAULT)
├── INDEX.md profile/ goals/ habits/ people/ areas/ journal/ reviews/The vault is plain files on your machine. self.os has no server, account or telemetry.
In a clone, vault/ is git-ignored. selfos init --git makes the vault its own repo;
push it only to a private remote.
The MCP server can only read and write inside the vault.
Agents are told never to store passwords, account numbers or ID numbers, and to record
only what you actually said (tagged [stated]) apart from clearly marked [inferred] notes.
Adapters for more runtimes, better coaching prompts and new check-in types are all welcome. See CONTRIBUTING.md and the good first issues.
This server cannot be deployed
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
