{"id":50916461,"url":"https://github.com/michaelasper/zsper","last_synced_at":"2026-06-16T15:32:17.654Z","repository":{"id":362627088,"uuid":"1259825837","full_name":"michaelasper/zsper","owner":"michaelasper","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-05T07:09:33.000Z","size":324,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T07:31:51.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michaelasper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-06-04T22:39:10.000Z","updated_at":"2026-06-05T07:09:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/michaelasper/zsper","commit_stats":null,"previous_names":["michaelasper/zsper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/michaelasper/zsper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelasper%2Fzsper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelasper%2Fzsper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelasper%2Fzsper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelasper%2Fzsper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michaelasper","download_url":"https://codeload.github.com/michaelasper/zsper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaelasper%2Fzsper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34412788,"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-06-16T02:00:06.860Z","response_time":126,"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-06-16T15:32:17.553Z","updated_at":"2026-06-16T15:32:17.640Z","avatar_url":"https://github.com/michaelasper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zsper\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eA local AI workspace with profile isolation, Brain storage, RAG, and agent-ready workflows.\u003c/b\u003e\n\u003c/p\u003e\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/michaelasper/zsper/main/install.sh | bash\nzsper profile init --mode work --root \"$HOME/.local/share/zsper/profiles/work\"\nzsper profile use work\n```\n\nZsper keeps local AI work organised by profile. Each profile owns its config,\nBrain data, retrieval indexes, ledgers, runtime files, and generated adapter\nsettings. Model serving is launched by Zsper through a profile-local oMLX\nruntime record and reached through local OpenAI-compatible endpoints.\n\n## Why Zsper\n\n| Capability | What it gives you |\n| --- | --- |\n| Profile isolation | Keep work, personal, and portable contexts separate by default. |\n| Local Brain storage | Store documents, chunks, citations, notes, tasks, and runtime metadata under the selected profile. |\n| Hybrid BM25 + dense retrieval | Balance exact terms with semantic recall. |\n| Citation objects | `brain answer` returns citation objects that can be inspected later. |\n| Profile-local model serving | Launch oMLX from Zsper and verify the local OpenAI-compatible endpoint. |\n| Append-only ledgers | Mirror mutating Brain records to profile-local JSONL for audit and recovery. |\n\n## Quick Start\n\n```bash\n# Install the CLI into your home directory.\ncurl -fsSL https://raw.githubusercontent.com/michaelasper/zsper/main/install.sh | bash\n\n# Create a profile. Installation does not choose one for you.\nzsper profile init --mode work --root \"$HOME/.local/share/zsper/profiles/work\"\n\n# Set the default profile for commands that omit --profile.\nzsper profile use work\n\n# Check the profile layout and policy.\nzsper profile doctor\n\n# Ingest and search local content.\nzsper brain ingest ~/notes/project.md\nzsper brain search project\n```\n\n## Profile Modes\n\nProfiles define the trust and runtime boundary for a workflow.\n\n| Mode | Use it for | Storage | Network posture |\n| --- | --- | --- | --- |\n| `work` | Professional projects and private work data | Postgres + pgvector | Local-first, remote access disabled |\n| `personal` | Personal projects and private personal data | Postgres + pgvector | Local-first, Tailscale Serve allowed |\n| `air` | Portable or lower-compute contexts | Profile-local SQLite path | Local-first, remote access disabled |\n\nThe mode is not the profile name. Choose names that match the machine or\nworkflow, such as `work`, `personal`, `portable`, `field`, or `travel`.\nOffline is a network-policy state, not a mode; any profile can start offline\nwith `--network-policy offline`.\n\nRead [Profile Modes](docs/architecture/profile-modes.md) for the design\nmodel and the exact defaults.\n\n## Install\n\nThe installer creates a managed checkout, virtual environment, wrapper command,\nand home-scoped configuration. It does not create a profile or set a default.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/michaelasper/zsper/main/install.sh | bash\n```\n\nAfter install:\n\n```bash\nzsper profile init --mode work --root \"$HOME/.local/share/zsper/profiles/work\"\nzsper profile use work\nzsper profile doctor\n```\n\nFor a portable profile:\n\n```bash\nzsper profile init \\\n  --mode air \\\n  --name portable \\\n  --root \"$HOME/.local/share/zsper/profiles/portable\"\nzsper profile use portable\n```\n\n## Develop From Source\n\n```bash\ngit clone https://github.com/michaelasper/zsper.git\ncd zsper\npython -m pip install -e \".[api,database,rag]\"\npython -m zsper --help\n```\n\nTo prepare a portable profile from a checkout:\n\n```bash\n./setup.sh --air --name portable\n```\n\n`./setup.sh --air` is a source-tree convenience wrapper. It prepares a portable\nprofile, creates a readiness note, ingests it, and verifies local search without\nhosted model, search, or extraction calls.\n\n## Repository Boundary\n\n`/Users/michaelasper/source/zsper` owns profiles, CLI, configs, Brain, RAG,\norchestrator, profile-local oMLX launch, local OpenAI-compatible HTTP checks,\ndocs, and tests.\n\nModel artifacts and serving processes stay profile-scoped. `zsper code start`\nlaunches `omlx serve`, records the PID and launch metadata in the selected\nprofile-local runtime directory, and `zsper code status` / `zsper code smoke`\nverify the selected local endpoint. Brain Compose must not include model\nserving; it consumes the same local endpoint as a client.\n\nSee [Repository Boundary](docs/architecture/repository-boundary.md) for the\nallowed local serving shape and disallowed dependency forms.\n\n## Documentation\n\n| Need | Start here |\n| --- | --- |\n| Understand profile modes | [Profile Modes](docs/architecture/profile-modes.md) |\n| Understand the platform shape | [Platform Overview](docs/architecture/platform-overview.md) |\n| Use offline state | [Offline State](docs/runbooks/offline-state.md) |\n| Develop locally | [Local Development](docs/runbooks/local-development.md) |\n| Run verification | [Testing](docs/runbooks/testing.md) |\n| Read the full product spec | [Ultimate Spec](docs/zsper-local-ai-platform-ultimate-spec.md) |\n| Follow implementation order | [Implementation DAG](docs/superpowers/plans/2026-06-04-zsper-platform-implementation-dag.md) |\n\n## Current Constraints\n\n| Constraint | Current path |\n| --- | --- |\n| Model artifact availability is local-machine specific | Install oMLX and model artifacts on the machine, then use `zsper code start/status/smoke` per profile. |\n| Rich parsing depends on local runtimes | Install the `rag` extras and keep Docling and embedding models available locally. |\n| Work and personal RAG use local Postgres services | Run profile Brain services before using Postgres-backed ingest/search flows. |\n| Offline state blocks hosted calls | Use `--network-policy offline` when a profile must avoid hosted model, search, extraction, and model-download calls. |\n\n## Troubleshooting\n\n### `zsper` is not on `PATH`\n\nAdd the wrapper directory to your shell:\n\n```bash\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\n### Python is too old\n\nZsper requires Python 3.12 or newer.\n\n```bash\nPYTHON=python3.12 ./setup.sh --air --name portable\n```\n\n### Search returns no results\n\nConfirm that the same profile was selected for ingest and search:\n\n```bash\nzsper profile list\nzsper brain ingest --profile work ./notes.md\nzsper brain search --profile work notes\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelasper%2Fzsper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaelasper%2Fzsper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaelasper%2Fzsper/lists"}