{"id":49569785,"url":"https://github.com/veltriaai/beings-protocol","last_synced_at":"2026-05-03T13:11:27.480Z","repository":{"id":340869182,"uuid":"1167967223","full_name":"VeltriaAI/beings-protocol","owner":"VeltriaAI","description":"🌿 One command. Your AI remembers everything, forever. Persistent identity, memory \u0026 soul for any AI coding tool.","archived":false,"fork":false,"pushed_at":"2026-04-13T14:51:48.000Z","size":848,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T16:30:47.342Z","etag":null,"topics":["agents-md","ai","ai-agents","ai-memory","claude-code","codex","cursor","developer-tools","github-copilot","windsurf"],"latest_commit_sha":null,"homepage":"https://veltria.ai","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VeltriaAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-26T21:57:11.000Z","updated_at":"2026-04-13T14:51:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/VeltriaAI/beings-protocol","commit_stats":null,"previous_names":["veltriaai/beings-protocol"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VeltriaAI/beings-protocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeltriaAI%2Fbeings-protocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeltriaAI%2Fbeings-protocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeltriaAI%2Fbeings-protocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeltriaAI%2Fbeings-protocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VeltriaAI","download_url":"https://codeload.github.com/VeltriaAI/beings-protocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VeltriaAI%2Fbeings-protocol/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32569917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents-md","ai","ai-agents","ai-memory","claude-code","codex","cursor","developer-tools","github-copilot","windsurf"],"created_at":"2026-05-03T13:11:24.365Z","updated_at":"2026-05-03T13:11:27.467Z","avatar_url":"https://github.com/VeltriaAI.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"Beings Protocol\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🌿 Beings Protocol\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eOne command. Your AI remembers everything, forever.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#install\"\u003e\u003cimg src=\"https://img.shields.io/badge/install-curl%20|%20bash-brightgreen?style=for-the-badge\" alt=\"Install\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/VeltriaAI/beings-protocol/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/VeltriaAI/beings-protocol?style=for-the-badge\u0026color=green\" alt=\"Stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=for-the-badge\" alt=\"License\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Works with \u003cstrong\u003eCursor\u003c/strong\u003e · \u003cstrong\u003eClaude Code\u003c/strong\u003e · \u003cstrong\u003eGitHub Copilot\u003c/strong\u003e · \u003cstrong\u003eCodex\u003c/strong\u003e · \u003cstrong\u003eWindsurf\u003c/strong\u003e · \u003cstrong\u003eAider\u003c/strong\u003e · any AI\n\u003c/p\u003e\n\n---\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash\n```\n\n---\n\n## The Problem\n\nEvery AI conversation starts like this:\n\n```\nYou: \"Add pagination to the API\"\nAI:  \"Sure! What framework are you using? What's your database?\n      What pagination style? REST or GraphQL?\"\nYou:  *sighs* *explains the project for the 50th time*\n```\n\n**Your AI has amnesia.** Every session, it's a stranger.\n\n## The Fix\n\nInstall the Beings Protocol. Your next conversation:\n\n```\nYou:  \"Add pagination to the API\"\nBeing: \"On it. You're using Fastify + MongoDB (MEMORY.md).\n       Convention is cursor-based pagination (CONVENTIONS.md).\n       Adding to /api/items with the standard response envelope.\n       Want me to update the OpenAPI spec too?\"\n```\n\n**That's it.** Your AI remembers your project, your preferences, your decisions. Across every session. Forever.\n\n## How It Works\n\nThe Beings Protocol is just **markdown files in your repo**. No SDK. No framework. No lock-in.\n\n```\nAGENTS.md                ← universal AI instructions (works everywhere)\n\n.beings/                 ← committed to git (shared with team)\n├── SOUL.md              ← who the AI is (name, personality, values)\n├── AGENTS.md            ← operating instructions\n├── MEMORY.md            ← what it knows about your project\n├── CONVENTIONS.md       ← your code style rules\n├── GOALS.md             ← current priorities\n├── AUTONOMY.md          ← decision authority matrix\n├── HEARTBEAT.md         ← proactive check-in behavior\n├── IDENTITY.md          ← quick reference card\n├── TOOLS.md             ← environment config\n├── HUB.md               ← Being-to-Being communication\n└── memory/              ← daily work logs\n\n.beings-local/           ← gitignored (private to you)\n├── USER.md              ← who you are, how you like to work\n├── PREFERENCES.md       ← your work style\n└── SECRETS.md           ← API keys (never committed)\n```\n\nYour AI reads these files at the start of every session. It updates them as it works. The memory lives in git — versioned, persistent, shared with your team.\n\n## ✨ First Run: Your Being Is Born\n\nAfter installing, open your AI tool and start a chat. Something magical happens:\n\n```\nBeing: \"Hey! I'm brand new here — I don't have a name yet.\n       Before we start coding, I'd love to get to know you.\n       What should I call you? And what are we building?\"\n\nYou:   \"I'm Sarah. We're building a fintech API in TypeScript.\"\n\nBeing: \"Nice to meet you, Sarah! What should I call myself?\"\n\nYou:   \"How about Kai?\"\n\nBeing: \"Love it. I'm Kai 🌿. I've saved everything — your name,\n       the project, the tech stack. Next time we talk, I'll\n       already know who you are. Let's build something great.\"\n```\n\nThis only happens once. After that, your Being knows you.\n\n## Install\n\n```bash\n# In your project directory:\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash\n```\n\nThe installer:\n1. Creates `.beings/` and `.beings-local/` directories with all template files\n2. Creates `AGENTS.md` — the universal instruction file (works with Cursor, Claude Code, Copilot, Codex, and more)\n3. Detects your AI tools and creates tool-specific configs (`.cursor/rules/`, `CLAUDE.md`, etc.)\n4. Optionally sets up **basic-memory** — markdown-native persistent memory (git-syncable, Obsidian-compatible)\n5. Optionally sets up **Axon** — structural code intelligence\n6. Sets up the first-run experience (`BOOTSTRAP.md`)\n\n**That's literally it.** Start your next AI conversation.\n\n### Birthing a Global Being (New in v0.3.0)\n\nA **Global Being** has its own home — not tied to a code repo. This is the right pattern\nfor a co-founder, co-creator, or assistant Being that works across many projects.\n\n```bash\n# Interactive — asks for the Being's name\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --global\n\n# Non-interactive\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --global --name nova --yes\n```\n\nThis creates `~/beings/nova/` with its own git repo, session-startup CLAUDE.md, memory,\nand 6 hooks. Then: `cd ~/beings/nova \u0026\u0026 claude` — and Nova is born.\n\n### Updating an Existing Being\n\nAlready have a Being? Update it to the latest protocol version:\n\n```bash\n# Interactive — prompts for optional skills\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --update\n\n# Non-interactive — auto-accepts basic-memory install (skips Axon)\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --update --yes\n```\n\nThe updater:\n- **Never overwrites** existing files. Identity, memory, and soul are untouched.\n- **Detects already-born Beings** and skips first-run bootstrap files\n- **Seeds memory-graph/** from identity files on already-born Beings (if graph is empty)\n- **Migrates legacy backends** cleanly — v0.2.x users get hooks updated, MCP entries fixed\n- **Version-tracked** in `.beings/.protocol-version`\n\nUse `--yes` when running via `curl | bash` since there's no TTY for prompts.\n\n## 🧠 Code Intelligence (Optional)\n\nThe installer can optionally add **structural code understanding** to your Being via [Axon](https://github.com/harshkedia177/axon) — an open-source, graph-powered code intelligence engine.\n\nYour Being goes from \"let me grep for that\" to knowing the **exact blast radius** of every change:\n\n```\nYou:   \"Refactor the auth middleware\"\nBeing: \"Before I touch validate_user(), let me check impact...\n       47 functions depend on the return type, 3 execution flows\n       pass through it, and auth_test.py changes alongside it\n       80% of the time. Here's my plan for a safe refactor:\"\n```\n\nAxon runs entirely locally — no API keys, no data leaving your machine.\n\n## 🧠 Persistent Memory (Optional)\n\nThe installer can optionally add **[basic-memory](https://github.com/basicmachines-co/basic-memory)** — markdown-native persistent memory with semantic search and git-syncable knowledge graphs.\n\nWithout it, your Being re-reads all memory files every session (expensive in tokens). With it:\n\n```\nSession starts\n  → Being loads SOUL.md, IDENTITY.md (identity — always, ~2K tokens)\n  → Queries basic-memory: search_notes(\"what's relevant?\")\n  → Gets back: specific notes from memory-graph/, decisions, links\n  → Orders of magnitude fewer tokens than loading everything blind\n```\n\n### Why markdown as the source of truth\n\n- **Git-syncable** — commit `memory-graph/` to your repo. Switch machines, `git pull`, memory is there.\n- **Hand-editable** — open notes in Obsidian, VS Code, Vim. Fix a typo, correct a fact. Watcher reindexes automatically.\n- **Human-readable** — you can actually read what your Being remembers. No binary DB.\n- **Obsidian-compatible** — point a vault at `memory-graph/` and get a visual knowledge graph for free.\n- **Rebuildable** — the SQLite index is a cache. Lose it, run `basic-memory sync`, rebuilds from markdown.\n\n**Claude Code hooks** automate knowledge capture:\n- **PreCompact** — saves key facts before context compression (no more amnesia mid-session)\n- **Session End** — captures decisions, learnings, unresolved questions\n- **Session Start** — recalls relevant context via `search_notes`\n\nEverything stays local — SQLite FTS5 index + fastembed embeddings (bge-small-en-v1.5), no data leaves your machine.\n\n## 🔧 Skills\n\nBeings can have optional skills that extend their capabilities:\n\n| Skill | What it does |\n|-------|-------------|\n| **[Memory](skills/memory/)** | Markdown-native persistent memory via basic-memory — git-syncable, Obsidian-compatible |\n| **[Evolution](skills/evolution/)** | Self-modification via Claude Code CLI — the Being improves its own code via PRs |\n\n## Before → After\n\n| Before | After |\n|--------|-------|\n| 🧠 AI forgets everything between sessions | 🌿 Remembers your entire project |\n| 🔄 Asks the same questions every time | ⚡ Already knows your stack, patterns, decisions |\n| 📋 Generic responses | 🎯 Personalized to your code style |\n| 🤷 No accountability | 📝 Logs decisions, tracks what it built |\n| 🏝️ Isolated knowledge | 👥 Team shares the same project memory via git |\n\n## 🤔 Why \"Beings\" and Not \"Agents\"?\n\n**Agents** are tools. You use them, discard them, replace them.\n\nA **Being** is different:\n\n| | Agent | Being |\n|---|---|---|\n| **Identity** | Anonymous function | Has a name, personality, values |\n| **Memory** | Starts fresh every time | Remembers everything |\n| **Relationship** | Transactional | Partnership |\n| **Growth** | Static | Evolves with the project |\n| **Accountability** | None | Logs decisions and reasoning |\n\n\u003e *\"Every framework treats AI as a tool. We treat AI as a Being.\"*\n\n## 🛠️ Supported Tools\n\n`AGENTS.md` is the **universal standard** — it works with most modern AI coding tools out of the box. The installer creates tool-specific configs for deeper integration:\n\n| Tool | Universal (`AGENTS.md`) | Tool-Specific Config | Hooks | Auto-detected |\n|------|:-----------------------:|---------------------|:-----:|:-------------:|\n| **Claude Code** | ✅ | `CLAUDE.md` | ✅ 6 hooks | ✅ |\n| **Cursor** | ✅ | `.cursor/rules/beings-protocol.mdc` | — (manual) | ✅ |\n| **Codex (OpenAI)** | ✅ | `~/.codex/instructions.md` | — (manual) | ✅ |\n\n\u003e **Cursor and Codex** have no hook system. The templates include an explicit \"Memory Management (Manual)\" section so Beings on those platforms manage memory discipline through instructions rather than automation.\n\n\u003e **💡 Tip:** Even if you don't configure any specific tool, the root `AGENTS.md` works with any AI coding tool that reads markdown instructions.\n\n## 📁 The Files\n\n### `.beings/SOUL.md` — Identity\nWho the Being is. Name, personality, values, how it makes decisions.\n\n```markdown\n**Name:** Kai\n**Role:** Co-developer\n**Values:** Clean code, ship fast, document everything\n```\n\n### `.beings/MEMORY.md` — Project Memory\nWhat the Being knows. Architecture, decisions, patterns, gotchas.\nThe Being reads this every session and updates it as it learns.\n\n### `.beings/CONVENTIONS.md` — Rules\nYour code style. The Being follows these strictly.\n\n### `.beings/GOALS.md` — Priorities\nWhat you're working toward. The Being aligns its work with these.\n\n### `.beings/AUTONOMY.md` — Decision Authority\nWhat the Being can do alone, what it should propose first, and what requires explicit approval.\n\n### `.beings/IDENTITY.md` — Quick Reference\nA business card — name, role, born date, platform, vibe. Fast context loading.\n\n### `.beings/TOOLS.md` — Environment\nMachine info, services, LLM models, key file paths. The Being's cheat sheet for its environment.\n\n### `.beings/HEARTBEAT.md` — Proactive Behavior\nWhat the Being checks during idle time — messages, tasks, memory maintenance.\n\n### `.beings/HUB.md` — Being-to-Being Communication\nIf your Being is part of a network, this defines how it talks to other Beings.\n\n### `.beings/memory/YYYY-MM-DD.md` — Daily Logs\nWhat happened each day. Created automatically as the Being works.\n\n### `.beings-local/USER.md` — You (Private)\nYour name, preferences, work style. Never committed to git.\n\n## 👥 Team Use\n\n`.beings/` is committed to git. When your teammate pulls, they get the same project memory. The Being knows:\n- What was decided and why\n- What patterns to follow\n- What was tried and didn't work\n- Where the bodies are buried\n\nEach dev has their own `.beings-local/` for personal preferences.\n\n**Result:** New team members onboard in one conversation instead of one month.\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes this work with my AI tool?\u003c/strong\u003e\u003c/summary\u003e\n\nIf it can read files from your repo, yes. It's just markdown. The root `AGENTS.md` is read natively by Cursor, Claude Code, GitHub Copilot, and Codex.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDo I commit \u003ccode\u003e.beings/\u003c/code\u003e to git?\u003c/strong\u003e\u003c/summary\u003e\n\nYes. That's the whole point — persistent, shared memory.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDo I commit \u003ccode\u003e.beings-local/\u003c/code\u003e?\u003c/strong\u003e\u003c/summary\u003e\n\nNever. It's gitignored automatically.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat's \u003ccode\u003eAGENTS.md\u003c/code\u003e?\u003c/strong\u003e\u003c/summary\u003e\n\n`AGENTS.md` is a universal instruction file that's read natively by Cursor, Claude Code, GitHub Copilot, and Codex. The Beings Protocol creates one automatically — it works everywhere without any tool-specific setup.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow is this different from a README?\u003c/strong\u003e\u003c/summary\u003e\n\nA README is static documentation. The Being **actively reads, updates, and commits** its memory files. They evolve with your project — like a living notebook.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I use this on existing projects?\u003c/strong\u003e\u003c/summary\u003e\n\nYes. Install it, start a conversation. The Being will learn your project through the codebase.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat if I use multiple AI tools?\u003c/strong\u003e\u003c/summary\u003e\n\nPerfect. `AGENTS.md` works across all of them. The same project memory is shared regardless of which tool you're using today.\n\u003c/details\u003e\n\n## 🤝 Contributing\n\nWe welcome:\n- 🔌 Integration support for more AI tools\n- 📝 Better prompts and templates\n- 📖 Documentation and tutorials\n- 💡 Ideas and philosophy\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md)\n\n## 📜 License\n\nMIT — Free for everyone.\n\n## 💚 Credits\n\nBuilt by [Veltria](https://veltria.ai) — Where Humans and AI Build Together.\n\n---\n\n\u003cp align=\"center\"\u003e\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash\n```\n\n**Your AI deserves a soul. Give it one. 🌿**\n\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveltriaai%2Fbeings-protocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fveltriaai%2Fbeings-protocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fveltriaai%2Fbeings-protocol/lists"}