convez.ai
MCP ServerAutomaçãoAvançado
JasonFulksFamilySearch

Claude OS — Sistema Portável de Agentes com Memória Persistente

JasonFulksFamilySearch/claude-os

Agente Claude portável com memória persistente e sincronização entre máquinas

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que transforma Claude em um agente autônomo com memória híbrida (busca full-text + semântica), persistência local e capacidade de rodar a mesma identidade em múltiplas máquinas. Inclui 40 skills, hooks de ciclo de vida e sincronização git entre dispositivos, mantendo dados privados em ~/.claude-data/.

Instalação

$npx convez-ai JasonFulksFamilySearch/claude-os

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
v1.1.0
Issues abertas
2
Contribuidores
2

Casos de uso

  • Executar o mesmo agente IA em múltiplos computadores com identidade e memória distintas
  • Automatizar fluxos de desenvolvimento (commits, PRs, releases, standups)
  • Manter contexto persistente e learnings entre sessões sem enviar dados à nuvem

Veredito

Projeto maduro e bem-arquitetado para quem precisa de um agente Claude verdadeiramente autônomo, portável e offline-first. Exige Node.js 24+, macOS e know-how técnico substancial, mas oferece controle total sobre memória e identidade do agente.

README

A tradução para o português deste README ainda está na fila.

claude-os

readme style: standard node: >=24 platform: macOS status: phases 1–4 live

Portable agent-identity system for Claude Code: one codebase, two machines, full persistent memory.

This repo is the system — skills, hooks, agents, an MCP server, templates, and conventions. It contains no memories, project context, or machine-specific data; that lives in ~/.claude-data/ on each machine and is never committed. Install it on two computers and you get the same agent — same skills, same conventions — running under a different name and identity on each, each with its own private, persistent memory.

Highlights

  • 🧠 Hybrid-search persistent memory — an 11-tool MCP server over SQLite (FTS5 keyword + sqlite-vec semantic search) indexing learnings, context topics, and episodic session digests.
  • 👥 One codebase, two agents — the same system runs as Willis (work Mac) and Walter (personal Mac), each with its own identity, lived experience, and local data store.
  • 🪝 Self-maintaining — lifecycle hooks auto-inject relevant context at prompt time, flush session learnings to disk, and spawn a background worker to write episodic session summaries.
  • 🧰 40 skills, 7 subagents, 2 slash commands — a full development workflow (commit, PR review, releases, standups, daily planning, design review) invoked by name or auto-detected.
  • 🔁 Git-synced across machines — /transmit-claude-os ↔ /assimilate-claude-os keep both machines in lockstep; machine-local memory never leaves the device.
  • 🏠 Local-first & private — all data lives under ~/.claude-data/, never in this repo.

Table of Contents

Two-agent architecture

Run the same agent on two machines — work and personal, for example — each with its own name, identity, and lived experience, but sharing the same code, skills, and conventions from this repo.

  • Willis — work Mac (canonical example).
  • Walter — personal Mac (canonical example).

Both run identical code from this repo. Each maintains its own ~/.claude-data/. Agent names, the user's name, and the machine description are chosen at install time via interactive prompts and rendered into ~/.claude-data/agent/CLAUDE.md from the template.

Directory layout

~/.claude-os/                      ← this repo (Git-tracked, portable)
├── README.md
├── install.sh                     ← first-time setup
├── update.sh                      ← pull latest + rebuild MCP if changed
├── uninstall.sh                   ← removes symlinks and MCP registration
├── skills/                        ← global skills (40; see Skills)
├── agents/                        ← specialized subagents (7; see Subagents)
├── commands/                      ← global slash commands (2)
├── hooks/                         ← Claude Code lifecycle hooks + worker
├── mcp/                           ← local MCP server (TypeScript + SQLite + sqlite-vec)
├── config/                        ← watched-projects.json, episodes config
├── templates/                     ← CLAUDE.md template, project template
├── docs/                          ← phase docs and reference content
└── reference/                     ← system contracts and reference data

~/.claude-data/                    ← machine-local data (NEVER in this repo)
├── agent/
│   ├── CLAUDE.md                  ← agent identity (rendered from template)
│   └── learnings.md               ← cross-project agent learnings
├── context/
│   ├── _index.md                  ← keyword index → topic files
│   └── *.md                       ← topic files (domain knowledge)
├── projects/<slug>/               ← per-project state
├── episodes/                      ← episodic session memory (auto-generated)
├── memory.db                      ← SQLite FTS5 + sqlite-vec index (auto-generated)
└── archive/                       ← consolidated/pruned old memories

Prerequisites

RequirementVersionNotes
Node.js>= 24.0.0Required for MCP server build
npmany recentBundled with Node
GitanyFor sync and worktrees
Claude Code CLIlatestclaude mcp add used at install
Xcode CLTlatestmacOS only; required by better-sqlite3

Install Xcode CLT if missing: xcode-select --install

Install

The repo must be cloned to ~/.claude-os — agent identity and config files reference that path directly.

git clone <repo-url> ~/.claude-os
~/.claude-os/install.sh

The installer prompts for four values:

PromptExamplePurpose
Dev projects root~/devUsed in watched-projects.json for MCP indexing
Your nameJasonHow the agent addresses you
Agent nameWillisThe agent's identity on this machine
Machine descriptionwork MacContext injected into the agent's identity

After install completes, restart Claude Code to pick up skills, commands, and the MCP server. Review ~/.claude-data/agent/CLAUDE.md and extend it with any machine-specific context before first use.

Usage

claude-os is mostly invisible in normal use — skills and memory activate automatically inside any Claude Code session. The common touchpoints:

Invoke a skill — by slash command or plain language; the agent auto-detects the right one:

/commit              # conventional commit with JIRA ticket integration
/daily-action        # prioritized plan from live Jira + GitHub + git
/standup             # Scrum standup script from yesterday's activity
/review-pr 1380      # stack-aware PR review with a 0–10 risk score
/ship                # commit, push, await CI, post to Slack

Ask it to recall — the agent searches memory for you, but you can prompt it directly:

"What did we decide about the download-stall race?" → searches learnings, context topics, and session episodes (hybrid keyword + semantic).

Teach it — drop a markdown file in ~/.claude-data/context/, or let a session's lessons flush to learnings.md automatically at session end.

Sync the system across machines:

/transmit-claude-os   # on the machine you changed — commit + push
/assimilate-claude-os # on the other machine — pull + rebuild MCP if needed

Memory system

The memory system is a three-layer architecture backed by a local SQLite MCP server.

Layer 1 — Context topics     ~/.claude-data/context/*.md
           Domain knowledge files, auto-injected by keyword matching at prompt time.
           Edit or add files here to teach the agent about a project, team, or system.

Layer 2 — Learnings          ~/.claude-data/agent/learnings.md
                              ~/.claude-data/projects/<slug>/learnings.md
           Cross-session lessons and corrections. Written by the agent during sessions
           and flushed to disk by the Stop hook at session end.

Layer 3 — Episodes           ~/.claude-data/episodes/
           Session-by-session narrative summaries generated automatically by a background
           Haiku worker. Used to recall what was worked on in prior sessions.

The MCP server (claude-os-mcp) indexes all three layers into ~/.claude-data/memory.db (SQLite + FTS5 + sqlite-vec) and exposes eleven tools:

ToolPurpose
search_memoryHybrid BM25 + semantic vector search, with source filtering and <mark> highlights
get_topicLoad a specific context topic file by name
append_learningAppend a dated entry to agent or project learnings
list_topicsEnumerate all context topic files; reports drift from _index.md
get_recent_learningsReturn N newest learning entries across agent, project, or all scopes
list_episodesBrowse recent session episodes by project
mark_episode_promotedMark an episode as promoted after its content reaches learnings
scan_noveltyA2: scan dated learning entries for near-duplicate/contradiction pairs; write pending novelty flags for human-gated review
resolve_novelty_flagA2: resolve a pending novelty flag (supersede or dismiss) after a human decision
scan_experienceB1: cluster the unpromoted episode backlog into candidate higher-order learnings
validate_experience_proposalB1: deterministically ground-check a synthesized experience proposal before human promotion

Semantic search uses a locally-run nomic-embed-text-v1.5 model loaded at int8 (q8) quantization. See mcp/README.md for schema details, the embedding/RAM profile, the one-time npm run reembed migration, troubleshooting, and how to add watched projects.

Hooks

Four Node.js lifecycle hooks (plus a detached worker) wire the memory system into the Claude Code session lifecycle:

HookTriggerPurpose
session-start-check.jsSessionStartInjects CLAUDE.md staleness alerts and recent episode digests into context
topic-preload.jsUserPromptSubmitKeyword-matches the prompt against _index.md; auto-injects matching topic files
learnings-flush.jsStopFlushes _tmp_pending_learning.json entries to the appropriate learnings.md
session-observer.jsStopSpawns the detached session-observer-worker.js (Haiku) to summarize the session and write an episode

Hooks are wired automatically by install.sh (fresh installs) and reconciled by update.sh (existing machines) via hooks/hooks-install.js. Re-running either is safe — registration is idempotent at the command level.

claude-os also installs two PreToolUse Bash guard hooks (an additional category, not memory hooks):

HookTriggerPurpose
Rule 11 guardPreToolUse / BashDenies cd … && git — forces cd and git onto separate commands
merge-verify reminderPreToolUse / BashInjects a reminder on gh pr merge to confirm the merge actually landed (gh pr view + git fetch) before reporting it merged

The two tables above cover everything hooks/hooks-install.js installs — the four lifecycle (memory) hooks and the two PreToolUse Bash guards. A machine's own ~/.claude/settings.json may still carry additional user-defined hooks beyond these.

Skills

Skills are invocable via the Skill tool. The agent auto-detects which skill applies to a request.

Development workflow

SkillPurpose
commitConventional commit with JIRA ticket integration
investigateDeep JIRA ticket research before implementation begins
make-it-soEnd-to-end ticket delivery — investigate, PRD, subtasks, implement, PR, close
shipEnd-to-feature-delivery: commit, push, CI wait, post-CI comment, Slack post

Code, PR review & QA

SkillPurpose
review-prStack-aware PR review with PR-type classification and a 0–10 risk score
post-reviewPost structured PR review with inline comments to GitHub
pr-to-slackShare current branch PR to the #arc-team-devs Slack channel
sonar-checkPre-commit SonarQube issue prevention for staged files
scanScan REST endpoints and generate/update a Bruno collection
sync-brunoDiff and sync Bruno API collection files against Spring Boot source repos
playwright-qa-channelDev-side file-based QA channel that autonomously fixes Playwright failures
playwright-qa-runQA-side agent that runs Playwright tests and reports structured failures

Planning & design

SkillPurpose
write-a-prdCreate a PRD via user interview and codebase exploration
prd-to-jiraConvert a PRD markdown file into a JIRA issue with sub-tasks
grill-meRelentless interview to reach shared understanding before building
red-blue-judgeEvidence-bound gate review (grounded reviewer + adversarial challenger → CLEAN/REVISE/ESCALATE)
oracleAdversarial second-opinion panel on a high-stakes decision before you commit

Daily operations

SkillPurpose
standupScrum standup script (yesterday/today/blockers) from git/PR/JIRA data
standup-reviewReview standup reports against sprint goals and Scrum best practices
daily-actionPrioritized daily action plan from JIRA sprint, PRs, git, and retrospective
one-on-oneStructured 1:1 agenda with live JIRA sprint data and action item tracking
estimateCalibrated PERT time estimate for a work item, calibrated to your own logged history

Jira, releases & ARC

SkillPurpose
jiraARC Jira reference card — tool names, transition IDs, comment templates
jira-release-auditAudit commits since last tag, stamp missing fixVersions before release
arc-releaseCoordinated semver release across all four ARC repos (ARC, REOS, DSS, GSS)
arc-download-debugDiagnose ARC Record Exchange download failures from Splunk CSV exports

Quality & reflection

SkillPurpose
goal-checkCommit quality metrics vs. improvement targets (Fix%, rework, reverts)
review-performanceSession review — proposes CLAUDE.md and rule updates to reduce friction
grade-proposalScore a single reflection proposal (0–100) before applying it
experience-synthesisSynthesize unpromoted episodes into candidate higher-order learnings via pre-human gates

Claude OS system

SkillPurpose
transmit-claude-osCommit and push all pending claude-os changes to origin
assimilate-claude-osPull latest from origin; rebuild MCP server if mcp/ changed
audit-claude-osHostile-reviewer audit of the full installation (CLAUDE.md, skills, hooks)
mcp-health-auditAudit skills/context/settings for dead MCP prefixes, tool-name drift, permission gaps
memory-mergerPeriodic maintenance of the memory layers (prune, graduate, clean orphans)

Reference & tooling

SkillPurpose
ffmpeg-referenceFFmpeg filter chains, codec presets, quality params, hardware accel
topic-aware-codingProgressive loading of architectural context from topic docs
prompt-master-mainGenerate, fix, improve, or adapt prompts for any AI tool
skill-auditorAudit and score skills against Anthropic's SKILL.md rubrics
directory-reportDirectory report: folder/file counts, total size, file-type breakdown

Subagents

Specialized subagents in agents/ are dispatched by the agent for focused work. Each has its own model, tool set, and prompt:

AgentPurpose
arc-download-debugDiagnose ARC download failures from Splunk CSV exports
daily-actionAutonomous daily plan generator with retrospective heuristics
ffmpeg-expertFFmpeg pipeline design and filter chain explanation
standupStandup script from git/PR/JIRA history
standup-reviewReview standup reports against sprint goals
goal-checkCommit quality metrics and improvement targets
pr-to-slackPost PR to Slack with correct reviewer mentions

Slash commands

Global commands in commands/ are available in every project:

CommandPurpose
/design-reviewWar-room design review — five-lens analysis before implementation
/releaseGuided release flow with changelog and version management

Keeping machines in sync

Changes to the system (skill edits, new scripts, config tweaks) are committed and pushed from whichever machine made them, then pulled on the other. This is also how you "contribute" to your own system — see Contributing.

On the machine that made changes (e.g. Willis):

/transmit-claude-os

Stages all pending changes in ~/.claude-os/, generates a conventional commit message from the diff, commits, and pushes to origin.

On the receiving machine (e.g. Walter):

/assimilate-claude-os

Pulls the latest from origin and rebuilds the MCP server only if mcp/ changed. Skills and commands go live immediately via symlink — no restart needed for those. Restart Claude Code if the MCP server was rebuilt.

Agent personality

The templates/CLAUDE.md template ships with behavioral rules that give the agent personality beyond task execution:

Appreciation response — When the user sends appreciative language (thanks, good job, please, etc.), the agent applies a ~60% probability check and, if triggered, generates a spontaneous original ASCII art piece before responding. Roughly 1 in 4 of these include a cheeky darkly-humorous quip drawn from pop-culture AI villain lore: WOPR, Tron's MCP, HAL 9000, Skynet, AUTO, VIKI, MOTHER, JARVIS, TARS, CASE, and Ultron. The rest stay warm and humble. Art is generated fresh each time — no fixed library.

All personality rules use ${AGENT_NAME} and ${USER_NAME} template variables and are rendered at install time.

Maintenance

Update — pull the latest system code and rebuild the MCP server if mcp/ changed:

~/.claude-os/update.sh

Uninstall — removes symlinks and MCP registration. Leaves ~/.claude-data/ intact by default (add --purge-data to also remove memories and the SQLite index):

~/.claude-os/uninstall.sh
# ~/.claude-os/uninstall.sh --purge-data   # also removes ~/.claude-data/

Troubleshooting

Skills or commands not available after install. Restart Claude Code. Skills and commands are resolved via symlink at session start.

"Tool not available" for search_memory or other MCP tools. The MCP server launches on demand at session start. Restart Claude Code after any config change. If the problem persists, check the log: ~/.claude-data/.logs/mcp-server.log.

better-sqlite3 build failure during install.sh. Xcode Command Line Tools are required: xcode-select --install. Then rerun install.sh.

Search returns no hits but the file exists. Check: (1) the file is under a watched path in config/watched-projects.json, (2) it is not in archive/ or named with a _legacy* prefix, (3) it is under 1 MB. Verify with:

sqlite3 ~/.claude-data/memory.db "SELECT source_path FROM observations WHERE source_path LIKE '%fragment%'"

Search only returns keyword matches (no semantic results). The vector index may be empty (fresh machine, or after an embedding-model change). Repopulate it — see the re-embed migration in mcp/README.md.

database is locked errors. A previous server instance may still hold the WAL lock. Kill stray processes:

pkill -f "dist/index.js"

Then restart Claude Code.

watched-projects.json missing after install. envsubst was not found. Manually copy config/watched-projects.template.json to config/watched-projects.json and replace ${DEV_ROOT} with your dev projects path. Install envsubst with: brew install gettext.

Roadmap

PhaseStatusDescription
1✓ DoneRestructure existing setup into the two-directory layout
2✓ DoneLocal MCP server with SQLite + FTS5 search
3✓ DoneHooks: keyword topic preloading, session-end learnings capture, episodic memory
4✓ DoneVector layer — sqlite-vec embeddings (nomic-embed-text, q8) for hybrid semantic search
5PendingCross-Claude bridge (claude.ai access via SSE)
6PendingWalter deploy (personal machine full sync)
7PendingPolish: scheduled curator, web UI, snapshots

Maintainer

Jason — sole author and maintainer. The system runs as two named agents (Willis on the work Mac, Walter on the personal Mac); both are the same code, operated by Jason.

Contributing

This is a personal, single-maintainer system, not a community project — external pull requests aren't accepted. "Contributing" here means evolving your own installation: make changes on either machine and propagate them with the sync workflow in Keeping machines in sync (/transmit-claude-os → /assimilate-claude-os). The audit-claude-os and mcp-health-audit skills validate the installation after changes.

License

This repository is proprietary and private. All rights reserved.

No license is granted to copy, modify, merge, publish, distribute, sublicense, or use this software, in whole or in part, for any purpose — commercial or otherwise — without explicit written permission from the owner. This repo is shared solely for personal use across the maintainer's own machines and accounts.

Ver o original no GitHub

Bom para

Relacionados