{
  "markdown": "# claude-bot\n\nPersistent Claude Code daemon with long-term memory, intelligent consolidation, and scheduled tasks. One always-on agent session + file-based cron scheduling + memory graph with folder organization.\n\n---\n\n## Install\n\n```bash\ngit clone https://github.com/michaelslain/claude-bot.git\ncd claude-bot\nbun install\nclaude plugin marketplace add ./\nclaude plugin install claude-bot@claude-bot-local\n```\n\nRestart Claude Code, then run `/claude-bot:setup` to initialize the daemon.\n\n### Requirements\n\n- [Bun](https://bun.sh) runtime\n- [Claude Code](https://claude.ai/download) installed and authenticated\n- **macOS:** launchd (automatic)\n- **Linux:** systemd (automatic)\n- **Windows:** _Not yet supported_\n\n---\n\n## Usage\n\nMemory tools are available in every Claude Code session via MCP. Talk to Claude naturally or use the tools directly.\n\n### Remember & Recall\n\nSave notes to your persistent memory graph:\n\n```\nremember({ \n  name: \"react-hooks-rules\", \n  type: \"fact\", \n  tags: [\"react\", \"rules\"], \n  content: \"Custom hooks must follow Rules of Hooks...\",\n  folder: \"projects\"  // optional, single-level\n})\n```\n\nSearch all notes or scoped to a folder:\n\n```\nrecall({ query: \"type:project tag:active\" })\nrecall({ query: \"tag:active\", folder: \"projects\" })  // folder scoped\n```\n\nQuery syntax: `type:`, `tag:`, `keyword:`, `link:`, `after:`, `before:` (all optional, combine with spaces)\n\nDelete notes:\n\n```\nforget({ name: \"projects/old-idea\" })  // folder-prefixed\nforget({ name: \"note\" })                // from root\n```\n\n### Organizing with Folders\n\nOptional single-level folders organize related notes:\n\n- By project: `projects/auth`, `projects/api`\n- By domain: `team/alice`, `infrastructure/kubernetes`\n- By time: `daily/2026-05-09`, `archive/2024`\n- By topic: `books/`, `research/`, `conferences/`\n\n**Rules:**\n- Alphanumeric, dash, underscore only: `[a-zA-Z0-9_-]+`\n- Single-level only (no nesting)\n- Backlinks are folder-agnostic (resolve across folders)\n\n```\nremember({\n  name: \"voting-standards\",\n  folder: \"moltbook\",  // creates moltbook/voting-standards\n  content: \"Voting rules for [[decision-making]]...\"  // links to any folder\n})\n```\n\n### Cron Jobs\n\nDefine recurring tasks as markdown files:\n\n```markdown\n---\nname: morning-summary\nschedule: 0 9 * * *\nmodel: sonnet\n---\n\nSummarize yesterday's notes. What are today's top 3 priorities?\n```\n\nManage via tools:\n\n```\ncron_create({ name: \"daily\", schedule: \"0 18 * * *\", prompt: \"Review today\" })\ncron_list()\ncron_run({ name: \"daily\" })\ncron_update({ name: \"daily\", enabled: false })\n```\n\n### Memory Consolidation\n\nThe bot automatically consolidates memory hourly (or manually):\n\n```\ndream_run()  // trigger consolidation\ndream_config({ intervalMs: 3600000 })  // 1 hour\ndream_status()\n```\n\nConsolidation merges duplicates, improves clarity, removes stale notes, and **respects folder boundaries** (never merges across folders).\n\n---\n\n## Examples\n\n### Project Knowledge Base\n\nOrganize project-specific notes in a folder:\n\n```\nremember({\n  name: \"architecture\",\n  folder: \"auth-system\",\n  type: \"project\",\n  content: \"JWT + refresh rotation pattern\"\n})\n\nremember({\n  name: \"JWT-tokens\",\n  folder: \"auth-system\",\n  type: \"fact\",\n  content: \"Stateless tokens with exp claim\"\n})\n\n# Later: search only auth project\nrecall({ query: \"type:project\", folder: \"auth-system\" })\n```\n\n### Daily Log\n\nAuto-collected session notes (type: `auto`) + manual promotion to daily log:\n\n```\nremember({\n  name: \"2026-05-09\",\n  folder: \"daily\",\n  type: \"daily\",\n  tags: [\"completed\"],\n  content: \"✓ Shipped feature X\\n→ Fix bug Y tomorrow\"\n})\n\nrecall({ query: \"type:daily\", folder: \"daily\" })\n```\n\n### Team Context\n\nCapture team knowledge with cross-folder links:\n\n```\nremember({\n  name: \"alice\",\n  folder: \"team\",\n  type: \"person\",\n  tags: [\"backend\", \"lead\"],\n  content: \"Lead engineer, owns [[auth-system]]. Async communication only.\"\n})\n\n# auth-system is in projects/ folder — link still works\n```\n\n---\n\n## Memory Graph\n\nLives at `~/.claude-bot/memory/`. Notes are markdown with YAML frontmatter:\n\n```markdown\n---\ntype: person | project | workflow | fact | preference | daily | auto\ntags: [tag1, tag2]\ncreated: 2026-05-08\nupdated: 2026-05-09\n---\n\nContent with [[backlinks]] to other notes.\n```\n\n### Backlinks\n\nNotes link to other notes via `[[note-name]]`. Links are **folder-agnostic** — a note in any folder can link to any other note by bare name:\n\n```markdown\n[[auth-system]]        # links to auth-system in any folder\n[[database-design]]    # resolves across all folders\n```\n\nUse `findBacklinks()` to discover all notes referencing a target.\n\n### Memory Decay\n\nDuring consolidation, stale, isolated notes (old dates + no backlinks) are candidates for deletion. Connected notes survive because they're part of the knowledge graph.\n\n---\n\n## Architecture\n\n```\n~/.claude-bot/                # Daemon home directory\n├── CLAUDE.md                 # Bot personality / behavior rules\n├── .mcp.json                 # MCP server config\n├── session-id                # Persistent session ID\n├── daemon.pid                # Daemon process ID\n├── memory/                   # Note storage\n│   ├── root-note.md\n│   ├── projects/\n│   │   ├── auth.md\n│   │   └── api.md\n│   ├── team/\n│   │   └── alice.md\n│   └── ...\n├── crons/                    # Cron job definitions\n│   ├── morning-summary.md\n│   └── ...\n└── logs/                     # Daemon stdout/stderr\n\nclaude-bot/ (project repo)\n├── server.ts                 # MCP server (memory, cron, dream, setup tools)\n├── package.json\n├── tsconfig.json\n├── .mcp.json\n├── README.md\n├── CLAUDE.md\n├── daemon/\n│   ├── index.ts              # Daemon entry point (session init, cron start)\n│   ├── session.ts            # Agent SDK session wrapper (create, resume, send)\n│   ├── cron.ts               # File-based cron scheduler\n│   ├── cron.test.ts          # Cron scheduler tests\n│   ├── process.ts            # Background process manager\n│   └── process.test.ts       # Process manager tests\n├── memory/\n│   ├── graph.ts              # Note CRUD, frontmatter, backlinks, folder support\n│   ├── graph.test.ts         # Graph tests\n│   ├── query.ts              # Query parser and executor\n│   ├── query.test.ts         # Query tests\n│   ├── search.ts             # Keyword scoring and search\n│   ├── search.test.ts        # Search tests\n│   └── dream.ts              # Memory consolidation via bot session\n├── bin/\n│   ├── recall-hook.ts        # UserPromptSubmit hook: injects memories into context\n│   └── collect-hook.ts       # SessionEnd hook: saves session transcript as auto note\n├── lib/\n│   ├── config.ts             # Configuration and defaults\n│   ├── config.test.ts        # Config tests\n│   ├── json.ts               # Shared JSON parsing, date utils\n│   ├── platform.ts           # OS-specific utilities (launchd/systemd)\n│   └── frontmatter.ts        # YAML frontmatter parsing\n├── skills/\n│   └── setup/SKILL.md        # Interactive setup skill\n└── .claude-plugin/\n    ├── plugin.json           # Plugin metadata\n    └── marketplace.json      # Marketplace configuration\n```\n\n---\n\n## MCP Tools Reference\n\n### remember\n\n```ts\nremember({\n  name: string,           // required\n  content: string,        // required\n  type?: NoteType,        // default: \"fact\"\n  tags?: string[],        // default: []\n  folder?: string         // optional: single-level folder\n})\n→ { ok: boolean, name: string, error?: string }\n```\n\n### recall\n\n```ts\nrecall({\n  query: string,         // required: filters like \"type:project tag:active\"\n  folder?: string        // optional: restrict to one folder\n})\n→ { ok: boolean, count: number, notes: MemoryNote[], error?: string }\n```\n\n**Query syntax:**\n- `type:fact` — filter by type\n- `tag:active` — filter by tag (multiple = AND)\n- `keyword:auth` — search content/name/tags\n- `link:other-note` — find notes linking to another\n- `after:2026-05-01` — updated on or after (inclusive)\n- `before:2026-05-10` — updated before (exclusive)\n\n### forget\n\n```ts\nforget({\n  name: string           // note name (may be folder-prefixed)\n})\n→ { ok: boolean, name: string, error?: string }\n```\n\n### cron_create\n\n```ts\ncron_create({\n  name: string,          // required\n  schedule: string,      // required: 5-field cron expression\n  prompt: string,        // required: task instructions\n  model?: \"opus\"|\"sonnet\"|\"haiku\",  // default: \"haiku\"\n  effort?: \"low\"|\"medium\"|\"high\",\n  catchup?: boolean,     // default: false\n  notify?: boolean       // default: false\n})\n```\n\n### cron_list, cron_run, cron_update, cron_delete\n\nSee CLAUDE.md for full details.\n\n### dream_run, dream_config, dream_status\n\nConsolidation tools. `dream_run()` triggers immediately; `dream_config()` updates interval; `dream_status()` shows current state.\n\n---\n\n## Guarantees & Constraints\n\n| Guarantee | Detail |\n|-----------|--------|\n| **Folder isolation** | Notes never merge across folders during consolidation |\n| **Backlink scope** | Backlinks resolve by bare name across all folders |\n| **Atomic writes** | All note operations are atomic via `Bun.write()` |\n| **Path safety** | Directory traversal attacks prevented; all paths validated |\n| **Single-level folders** | Nesting auto-flattened (`a/b/c` → `a-b-c`) |\n| **Folder name validation** | Regex `[a-zA-Z0-9_-]+` enforced |\n\n---\n\n## Development\n\n### Setup\n\n```bash\nbun install\nbun test  # Run tests (116+ test cases)\nbunx tsc --noEmit  # Type check\n```\n\n### Running Locally\n\n```bash\nbun run server.ts  # Start MCP server on stdio\n```\n\n### Tech Stack\n\n- **Runtime:** Bun\n- **AI:** `@anthropic-ai/claude-agent-sdk`\n- **MCP:** `@modelcontextprotocol/sdk`\n- **Daemon:** launchd (macOS) / systemd (Linux)\n- **Storage:** Markdown files with YAML frontmatter\n\n---\n\n## Testing\n\n```bash\nbun test                    # Run all tests\nbun test memory/            # Run memory tests only\nbun test --watch            # Watch mode\n```\n\n**Coverage:**\n- 51 graph tests (CRUD, backlinks, folders, sanitization)\n- 53 query tests (parsing, execution, folder filtering)\n- 100% pass rate\n\n---\n\n## License\n\nInternal (Anthropic).\n",
  "bytes": 10041,
  "sha": "2a5832308dee14cba1edf302eabfe7529329b13d466b9f80a3ca3b7f88654589",
  "repo_slug": "michaelslain/claude-bot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_michaelslain_claude_bot_claude_bot_9f0e1da4/readme"
}