{"id":50275757,"url":"https://github.com/opencow42/metabrain","last_synced_at":"2026-05-31T00:01:13.641Z","repository":{"id":358657820,"uuid":"1240977522","full_name":"OpenCow42/metaBrain","owner":"OpenCow42","description":"A local document memory for AI agents and humans. A tool to manage large sets of MDs 💽 and JSON alike","archived":false,"fork":false,"pushed_at":"2026-05-25T17:36:03.000Z","size":5340,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T20:22:44.852Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenCow42.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T20:08:11.000Z","updated_at":"2026-05-25T17:36:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/OpenCow42/metaBrain","commit_stats":null,"previous_names":["opencow42/metabrain"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/OpenCow42/metaBrain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCow42%2FmetaBrain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCow42%2FmetaBrain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCow42%2FmetaBrain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCow42%2FmetaBrain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenCow42","download_url":"https://codeload.github.com/OpenCow42/metaBrain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenCow42%2FmetaBrain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33714033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-05-27T20:03:38.375Z","updated_at":"2026-05-31T00:01:13.629Z","avatar_url":"https://github.com/OpenCow42.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metaBrain\n\n[![Swift Package Index](https://img.shields.io/endpoint?url=https://swiftpackageindex.com/api/packages/OpenCow42/metaBrain/badge?type=swift-versions)](https://swiftpackageindex.com/OpenCow42/metaBrain)\n[![Swift Package Index](https://img.shields.io/endpoint?url=https://swiftpackageindex.com/api/packages/OpenCow42/metaBrain/badge?type=platforms)](https://swiftpackageindex.com/OpenCow42/metaBrain)\n\n🪟 Windows is supported alongside macOS and Linux.\n\n`metaBrain` is a local document memory for AI agents and tools.\n\nIt gives an agent one durable, searchable place to keep notes, source snippets,\ntask context, metadata, tags, links, and version history. Instead of spreading\nstate across loose `.md`, `.json`, and scratch files, `metaBrain` stores content\nin a compact LevelDB-backed database while keeping it discoverable through a\nsmall CLI.\n\nThe first public release ships the `mb` command-line tool and the\n`MetaBrainCore` Swift library.\n\n## Install On macOS\n\nInstall from the public OpenCow42 Homebrew tap:\n\n```bash\nbrew tap OpenCow42/tap \u0026\u0026 brew install mb\n```\n\n## Install On Ubuntu\n\nInstall from the public OpenCow42 APT repository on Ubuntu 24.04 or 26.04.\nThe package name is `metabrain`, and it installs the `mb` command.\n\nUbuntu 24.04:\n\n```bash\necho 'deb [trusted=yes] https://opencow42.github.io/apt-repo ubuntu24.04 main' | sudo tee /etc/apt/sources.list.d/opencow.list\nsudo apt update\nsudo apt install metabrain\n```\n\nUbuntu 26.04:\n\n```bash\necho 'deb [trusted=yes] https://opencow42.github.io/apt-repo ubuntu26.04 main' | sudo tee /etc/apt/sources.list.d/opencow.list\nsudo apt update\nsudo apt install metabrain\n```\n\nThe current Ubuntu package is published for `amd64`. The repository uses\n`trusted=yes` until signed APT metadata is available.\n\n## Why Try It\n\n- **One local memory per workspace.** The default store lives at\n  `.metabrain/store.leveldb`, so agents can find it without configuration.\n- **Filesystem-like paths.** Documents live at paths such as `/notes/today` or\n  `/projects/metabrain/release-plan`, making memory easy to browse and explain.\n- **Searchable content.** Current document chunks are indexed for lexical search\n  with tag, metadata, and path filters.\n- **Versioned edits.** Updates keep full snapshots, and unified-diff patches can\n  change stored documents without rewriting whole bodies by hand.\n- **Structured enough to grow.** Documents carry metadata, tags, references, and\n  retained versions, while the implementation stays embeddable.\n\n## Requirements\n\n- macOS 15 or newer, or Ubuntu 24.04 / 26.04 on amd64\n- Swift 6.3 or newer when building from source\n\n## Build From Source\n\n```bash\nswift build\n```\n\n## Try The CLI\n\nCreate a store, write a note, browse it, search it, and read it back:\n\n```bash\nmb init\nmb put /notes/today \"Remember the lexical store.\" --tag planning --meta source=agent\nmb list /notes --recursive --dates\nmb tree --max-depth 2\nmb search \"lexical store\" --tag planning\nmb get /notes/today\n```\n\nThe default store is `.metabrain/store.leveldb`. Pass `--store \u003cpath\u003e` to any\ncommand when a workspace uses a different store location.\n\n## Agent Workflow\n\nUse `put` for durable facts and summaries:\n\n```bash\nmb put /tasks/release-checklist \\\n  \"Prepare first public release, confirm license, and publish the CLI.\" \\\n  --tag release \\\n  --meta status=active\n```\n\nUse `--body-file` for larger notes:\n\n```bash\nmb put /research/leveldb-notes --body-file notes.md --tag research\n```\n\nUse `patch` when an agent has a focused unified diff:\n\n```bash\nmb patch /tasks/release-checklist --patch-file change.diff\nmb patch /tasks/release-checklist --patch-file change.diff --check\n```\n\nExport a subtree as JSONL, optionally with UTF-8 body files:\n\n```bash\nmb dump /tasks --output-dir ./metabrain-dump\n```\n\nInspect history and prune retained versions:\n\n```bash\nmb versions /tasks/release-checklist\nmb prune /tasks/release-checklist --keep-last 5\n```\n\nAsk the CLI what it can do:\n\n```bash\nmb version\nmb --help\nmb help search\nmb help dump\n```\n\n## Commands\n\n- `version` prints the current release tag and checks GitHub for newer releases.\n- `init` creates or opens a store.\n- `put` creates or updates a document at a path.\n- `patch` applies a single-file unified diff to an existing document body.\n- `move` relocates an existing document to a new path without changing its ID.\n- `get` reads a document by path or stable document ID.\n- `list` lists stored document paths in a virtual folder.\n- `tree` prints the stored document path tree.\n- `search` searches current document content with optional filters.\n- `dump` exports documents as JSONL and optional body files.\n- `versions` lists retained snapshots for a document.\n- `prune` applies a retention policy to document versions.\n- `delete` removes a current document and all retained versions.\n- `remove-version` removes one retained historical version.\n\n## Project Shape\n\nThis repository is a Swift package with two products:\n\n- `MetaBrainCore`: the shared library for storage, indexing, retrieval, and\n  domain behavior.\n- `mb`: the command-line tool.\n\nThe CLI stays thin. Shared behavior belongs in `MetaBrainCore` so every future\ninterface uses the same underlying model.\n\nThe native Apple platform GUI lives in the sibling\n[`metaBrainExplorer`](../metaBrainExplorer) repository. It depends on\n`MetaBrainCore` and owns app-specific state, presentation, and Apple UI\nintegration.\n\n## Implemented Store Behavior\n\nThe current store is embedded and LevelDB-backed. Document records, versions,\nand current chunks are Codable JSON envelopes stored through adaptive ZSTD\ncompression. Ordered index keys remain plain ASCII strings for prefix scans.\nThe default ZSTD compression level is `3`, and LevelDB paranoid checks are\nenabled by default.\n\n### Store Format Compatibility\n\nRecord envelopes include an internal schema version. This tool treats schema\nversion `1` as the current writable format. Later schema versions are parsed as\nfuture versions instead of invalid versions.\n\nWhen a store contains future-version records, commands should still read them\nwhen the existing key layout and Codable payload remain compatible. This lets\nolder `mb` binaries inspect a newer store where possible. Mutating commands\nrefuse to overwrite, prune, or delete future-version records and return a clear\nupgrade-required store error instead of silently downgrading newer data. In\npractice, `get`, `list`, `tree`, `search`, `dump`, and `versions` can continue\nto work for compatible future records, while `put`, `patch`, `move`, `prune`,\n`delete`, and `remove-version` fail at the affected newer records.\n\nCompatibility is best-effort, not a promise that every future format can be\nread by older binaries. A future release may add required payload fields or a\nnew key layout that old tools cannot decode. Older tools should fail\ngracefully in those cases.\n\nImplemented behavior includes:\n\n- Async `MetaBrainStore` facade over one explicit store path.\n- Stable lowercase ASCII document IDs.\n- Normalized absolute slash paths.\n- Whole-document writes, path-preserving updates, and explicit moves.\n- Unified-diff body patches for existing documents.\n- Full-snapshot version history with keep-all, keep-last-N, and time-window\n  retention policies.\n- Current-body chunking with overlap for search.\n- Lexical search ranked by term coverage, frequency, and locality.\n- Tag, metadata, and path-prefix search filters.\n- Internal reference indexes for resolved document links.\n- Virtual folder browsing through explicit `tree/` indexes.\n- JSONL subtree dumping with optional versioned body files.\n\nFor cross-document relationships, prefer document ID references over path\nreferences when the relationship is meant to survive reorganization. A move\npreserves the moved document's stable ID, so `--ref-id` links continue to point\nat the same document. Path references are useful location aliases, but stored\npath reference values are not rewritten automatically when a document moves.\n\n## Development\n\nRun the normal checks before handing off implementation work:\n\n```bash\nswift build\nswift test\ngit diff --check\n```\n\nThe project also has deeper coverage, smoke-test, fuzzing, benchmark, and\nrelease workflows for maintainers. Maintainer smoke tests use `ripgrep`. See\nthe project documents below when you need those paths.\n\n## Project Documents\n\n- [MANIFESTO.md](MANIFESTO.md) explains the project vision and principles.\n- [ARCHITECTURE.md](ARCHITECTURE.md) records the compressed document store design.\n- [COMPLEXITY.md](COMPLEXITY.md) estimates command and store-method costs.\n- [AGENTS.md](AGENTS.md) defines repository rules for coding agents and contributors.\n\n## License\n\n`metaBrain` is licensed under the BSD 3-Clause License. See [LICENSE](LICENSE).\n\nThird-party dependencies retain their own licenses, including BSD 3-Clause for\n`swift-leveldb` and its vendored LevelDB source. Zstandard, provided by `zstd`,\nis dual-licensed under BSD or GPLv2; this project uses it under the BSD option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencow42%2Fmetabrain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopencow42%2Fmetabrain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopencow42%2Fmetabrain/lists"}