{"id":46266929,"url":"https://github.com/adrozdenko/soleri","last_synced_at":"2026-04-03T19:01:58.358Z","repository":{"id":340377360,"uuid":"1165708359","full_name":"adrozdenko/soleri","owner":"adrozdenko","description":"An open-source framework for building AI assistants that learn, remember, and grow with you.","archived":false,"fork":false,"pushed_at":"2026-04-02T18:57:57.000Z","size":26414,"stargazers_count":5,"open_issues_count":60,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T03:16:36.198Z","etag":null,"topics":["ai","ai-assistants","brain","claude-code","framework","knowledge","mcp","memory","open-source","personas","typescript","vault"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adrozdenko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-24T13:09:45.000Z","updated_at":"2026-04-02T18:58:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/adrozdenko/soleri","commit_stats":null,"previous_names":["adrozdenko/soleri"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/adrozdenko/soleri","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrozdenko%2Fsoleri","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrozdenko%2Fsoleri/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrozdenko%2Fsoleri/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrozdenko%2Fsoleri/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adrozdenko","download_url":"https://codeload.github.com/adrozdenko/soleri/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adrozdenko%2Fsoleri/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31371647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["ai","ai-assistants","brain","claude-code","framework","knowledge","mcp","memory","open-source","personas","typescript","vault"],"created_at":"2026-03-04T02:22:12.264Z","updated_at":"2026-04-03T19:01:58.350Z","avatar_url":"https://github.com/adrozdenko.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eS O L E R I\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/adrozdenko/soleri/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/adrozdenko/soleri/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/soleri\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/soleri.svg\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/adrozdenko/soleri/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/soleri.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/soleri\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/soleri.svg\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/node/v/soleri.svg\" alt=\"Node version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nEvery AI session starts from zero. You explain your conventions, your architecture, your preferences — and then the session ends and it's all gone. You do it again tomorrow. And the day after that.\n\n**Your expertise should compound — not evaporate.**\n\nSoleri is an open-source second brain builder. It gives your AI assistant persistent memory, structured knowledge, and intelligence that grows with every session.\n\n## How It Works\n\nYour second brain is a **folder**. No TypeScript, no build step, no `npm install`.\n\n```\nmy-brain/\n├── agent.yaml          # what do I know\n├── instructions/       # how I think\n├── workflows/          # how I work\n├── knowledge/          # what I've learned\n└── .mcp.json           # connects to Soleri Knowledge Engine\n```\n\nyour AI editor reads the folder natively. The **Knowledge Engine** provides the infrastructure — a vault that remembers, a brain that learns what works, and memory that carries across every project and conversation. The more you use it, the smarter it gets.\n\n## What You Get\n\n**Platform:** macOS, Linux, and Windows (via Git Bash). See the [Windows setup guide](https://soleri.ai/docs/guides/windows/) for details.\n\n**Prerequisites:**\n- [Node.js 18+](https://nodejs.org) (npm ships with it)\n- An MCP-compatible AI editor: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), or [OpenCode](https://github.com/opencode-ai/opencode)\n\n```bash\nnpx --yes soleri create my-brain       # Build your second brain (~3 seconds)\nnpx --yes soleri install               # Connect to your editor\nnpx --yes soleri dev                   # Start learning\nnpx --yes soleri doctor                # Check system health\n```\n\n\u003e **npx vs global install:** The commands above use `npx --yes` which downloads and runs the CLI without a global install. The `--yes` flag skips the confirmation prompt. If you prefer a persistent install, run `npm install -g soleri` and then use bare `soleri` commands (e.g. `soleri create my-brain`).\n\nYour second brain is ready the moment it's created. No build step needed.\n\n### Persona System\n\nEvery agent has a composable persona that defines HOW it communicates — voice, traits, quirks, opinions, and cultural texture. New agents ship with the Italian Craftsperson persona (inspired by Paolo Soleri): warm, opinionated about quality, universal across domains. Define your own in `agent.yaml` under the `persona:` block.\n\n### The Engine\n\n**Vault** — Domain-separated knowledge store. Patterns, anti-patterns, workflows, and architecture decisions organized by domain, graph-connected for cross-domain discovery. Self-maintaining: deduplication, decay detection, and confidence tracking happen automatically. Knowledge packs export and import with Zettelkasten links — new agents inherit the full knowledge graph, not just orphaned entries.\n\n**Brain** — Learning loop that captures intelligence from real sessions. Search combines SQLite FTS5 with TF-IDF scoring. Tracks pattern strength with confidence scores, surfaces high-confidence patterns first, and operates on a rolling window. No manual tagging — capture is automatic.\n\n**Memory** — Cross-session, cross-project continuity. Switch conversations, switch projects — nothing is lost. Link projects as related, parent/child, or fork and search across all of them with weighted relevance.\n\n**Playbooks** — Multi-step validated procedures stored in the vault. Token migrations, component setup, contrast audits — each step includes validation criteria so the agent can execute and verify autonomously.\n\n### Second Brain (v8.0)\n\nThe engine now acts as a true second brain — it doesn't just store knowledge, it actively helps you use it:\n\n- **Two-pass search** — Scan titles first, load only what's relevant. Saves 60-80% context tokens.\n- **Session briefing** — Start every session with context: what you did last time, active plans, recent learnings, brain recommendations.\n- **Learning radar** — Automatically detects patterns from corrections, search misses, and workarounds. Captures silently or queues for review.\n- **Content synthesis** — Turn vault knowledge into briefs, outlines, talking points, or post drafts.\n- **Skill chains** — Multi-step workflows with data flow between steps and approval gates.\n- **External ingestion** — Ingest articles, transcripts, and notes from outside coding sessions.\n- **Evidence-based reconciliation** — Cross-references plan tasks against actual git changes.\n- **OAuth discovery** — Uses your Claude Code subscription for free Anthropic API access (macOS + Linux).\n\n### Architecture\n\nTwo layers, cleanly separated:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│  Agent Folder     agent.yaml · instructions/ · workflows/ │\n│  (the shell)      knowledge/ · skills/ · CLAUDE.md (auto) │\n├─────────────────────────────────────────────────────────┤\n│  Knowledge Engine 20 modules: vault · brain · curator · planner │\n│  (the brain)      memory · archive · sync · review · links … │\n├─────────────────────────────────────────────────────────┤\n│  Transports       MCP · HTTP/SSE · WebSocket · Telegram   │\n└─────────────────────────────────────────────────────────┘\n```\n\n- **Agent Folder** — Plain files (YAML, Markdown, JSON). your AI editor reads them natively. No code generation, no compilation.\n- **Knowledge Engine (`@soleri/core`)** — Persistent state for all agents. Vault (SQLite + FTS5), Brain (hybrid TF-IDF + optional Cognee vector search), Planner (state machine), Curator (dedup, grooming), and cross-project memory.\n- **Extensions** — Two tiers: **Domain Packs** (npm packages like `@soleri/domain-design`) for published intelligence, and **Local Packs** (project directories with `soleri-pack.json`) for project-specific knowledge, skills, and hooks. All extensions receive a narrowed `PackRuntime` (vault + projects + session checks).\n- **Model-agnostic** — The engine runs on pure SQLite FTS5 and TF-IDF math. Works without API keys. Pure SQLite — no external services required.\n\n### Persistence\n\nSoleri uses **SQLite** (via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)) as its sole storage engine. This is a deliberate architectural choice:\n\n- **FTS5** for full-text search with BM25 ranking — no external search service needed\n- **WAL mode** for concurrent reads during writes\n- **Zero ops** — no database server to provision, no connection strings to manage\n- **Tested at scale** — 10K vault entries with sub-50ms FTS search (see `vault-scaling.test.ts`)\n\nThe `PersistenceProvider` interface exists for future extensibility, but SQLite is the only implemented and tested backend.\n\n### Packages\n\n| Package                                   | Description                                                                          |\n| ----------------------------------------- | ------------------------------------------------------------------------------------ |\n| [`@soleri/core`](packages/core)           | Knowledge Engine — vault, brain, planner, curator, `registerEngine()`, engine binary |\n| [`@soleri/forge`](packages/forge)         | Agent scaffolder — generates file-tree agents from config                            |\n| [`@soleri/cli`](packages/cli)             | Developer CLI — create, install, dev, doctor, packs, hooks                           |\n| [`create-soleri`](packages/create-soleri) | `npm create soleri` shorthand                                                        |\n| [`@soleri/domain-*`](packages/)           | Domain packs — design, component, figma, code-review                                 |\n\n### Guides\n\n- [**Knowledge Management**](docs/guides/knowledge-management.md) — How to feed, train, and curate your agent's brain. The daily rhythm: search, capture, curate.\n\n### Knowledge Packs\n\nInstall expertise in one command:\n\n| Tier          | Source           | Cost |\n| ------------- | ---------------- | ---- |\n| **Starter**   | Ships with agent | Free |\n| **Community** | npm registry     | Free |\n\n```bash\nnpx --yes soleri install-knowledge ./bundles/react-patterns\n```\n\n### Hook Packs\n\nAutomated quality gates and safety guardrails for Claude Code:\n\n```bash\nnpx --yes soleri hooks add-pack safety          # Anti-deletion staging for destructive commands\nnpx --yes soleri hooks add-pack flock-guard     # Parallel agent lockfile protection\nnpx --yes soleri hooks add-pack clean-commits   # No AI attribution in git commits\nnpx --yes soleri hooks add-pack typescript-safety  # Block unsafe TS patterns\nnpx --yes soleri hooks add-pack a11y            # Accessibility enforcement\nnpx --yes soleri hooks add-pack full            # All of the above\n```\n\nConvert your own skills into automated hooks:\n\n```bash\nnpx --yes soleri hooks convert my-hook --event PreToolUse --matcher \"Write|Edit\" \\\n  --pattern \"**/src/**\" --action remind --message \"Check guidelines\"\nnpx --yes soleri hooks test my-hook             # Validate with fixtures\nnpx --yes soleri hooks promote my-hook          # remind → warn → block\n```\n\n### Teams \u0026 Ops\n\n- **Connected vaults** — Link agent, project, and team vaults with automatic search priority.\n- **Cross-project knowledge** — Link projects and search across them with weighted relevance.\n- **Health checks** — `npx --yes soleri doctor` reports engine version, domain status, vault health, brain tracking, and team sync state.\n\n## Testing\n\n```bash\nnpm test                # Unit tests — 313 files, 3,900+ tests\nnpm run test:e2e        # E2E tests — 900+ tests across 30 files\n```\n\nThe E2E suite covers: file-tree agent full pipeline (scaffold → engine boot → MCP → ops), all 20 engine modules across 8 vault-family facades, over-the-wire MCP transport, data persistence, concurrency, CLI commands, hook pack validation, and domain pack validation.\n\n## Contributing\n\nFrom fixing typos to building domain modules — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Roadmap\n\n[GitHub Milestones](https://github.com/adrozdenko/soleri/milestones)\n\n## License\n\n[Apache 2.0](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Named after \u003ca href=\"https://en.wikipedia.org/wiki/Paolo_Soleri\"\u003ePaolo Soleri\u003c/a\u003e, the architect who believed structures should be alive, adaptive, and evolving.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://soleri.ai\"\u003esoleri.ai\u003c/a\u003e · \u003ca href=\"https://www.npmjs.com/package/soleri\"\u003enpm\u003c/a\u003e · \u003ca href=\"https://github.com/adrozdenko/soleri/issues\"\u003eIssues\u003c/a\u003e · \u003ca href=\"https://github.com/adrozdenko/soleri/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrozdenko%2Fsoleri","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadrozdenko%2Fsoleri","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadrozdenko%2Fsoleri/lists"}