Stop re-explaining yourself to every AI tool.

Holoself keeps approved personal context in readable local files, links it to independent projects through task-specific lenses, and asks before project discoveries become durable knowledge.

Plain language: your context, under your control, reusable across tools and projects.

Technical description: an open-source, local-first whole-person context protocol built on Markdown, project links, lenses, provenance, deterministic local indexing, and explicit proposal review.

Projects own their artifacts. Self owns approved reusable personal knowledge.

Why Holoself

AI app memory is often opaque and tool-bound. Profile files are easy to duplicate and let drift. Central personal vaults tend to absorb project work that belongs elsewhere. Holoself separates these concerns:

flowchart LR
    S[(Canonical self<br/>Markdown)] -->|lens + privacy policy| P[Independent<br/>linked project]
    P -->|evidence-backed discovery| Q[Pending<br/>proposal]
    Q -->|explicit human review| S

    classDef self fill:#10231d,color:#fffaf4,stroke:#245f50,stroke-width:2px
    classDef project fill:#dceee3,color:#10231d,stroke:#245f50,stroke-width:2px
    classDef review fill:#fffaf4,color:#10231d,stroke:#f09a62,stroke-width:2px
    class S self
    class P project
    class Q review

• One whole person, many lenses. Built-in and optional private registry-backed lenses change explicit read scope and relevance—not identity or publication approval. Custom base lenses never inherit document access.
• Independent projects. Applications, research, posts, calendars, and execution notes stay with their projects.
• Review before memory. Projects propose; only explicit approval changes canonical self context.
• Inspectability. Markdown is source of truth. Generated packets and indexes are disposable.
• Provenance. Context and accepted claims identify their source files.
• Local by default. CLI performs no network requests and requires no hosted account.

Product status

| Capability | Status | |---|---| | Private Markdown data root | Stable | | Project metadata links and lenses | Available | | Context packets and JSON adapters | Available | | Proposal/review workflow | Available | | Deterministic local index and federated search | Available | | Local project-bound STDIO MCP | Available; preferred per platform after native verification | | Overlap/conflict/stale reports | Available | | Legacy packet export and filesystem junction | Supported compatibility path | | SQLite/FTS acceleration | Planned, optional | | Embedding/vector search | Planned, optional | | Hosted sync or account | Not provided | | npm registry package | Available as holoself-ai |

Start here

Requirements: Node.js 20+ and a private location for personal context.

Choose the path that matches what you want to do:

| I want to… | Start with | |---|---| | Set up Holoself and see it working | Quickstart | | Manage context visually | Workbench guided tour | | Give an AI project relevant context | First linked project | | Solve a specific everyday task | Common use cases | | Integrate or assess the data model | Architecture |

npm install --global holoself-ai
holoself init --data-dir C:/private/my-self
holoself doctor --data-dir C:/private/my-self
holoself validate --data-dir C:/private/my-self

These commands install the holoself package bin on PATH. A repository checkout remains supported through node bin/holoself.mjs; both forms execute the same CLI. MCP clients use the installed holoself form because they launch the command outside this shell. See CLI invocation and reference.

Install the declarative agent skill separately when useful:

npx skills add smota/holoself --skill holoself

The skill contains instructions, not personal data. The quickstart below works without installing it.

Optional Workbench

Workbench is the easiest way to browse your context, understand linked projects, review proposed knowledge, and see what needs attention. It is local and optional; Markdown and the CLI remain the source of truth and control surface.

holoself web --root C:/private/my-self

It opens on 127.0.0.1 and requires no hosted account. Start with the screen-by-screen Workbench tour. Architecture, connector, and trust-boundary details remain in the Workbench reference.

Link an independent project

holoself link add \
  --project C:/work/my-project \
  --self C:/private/my-self \
  --lens career

holoself context \
  --project C:/work/my-project \
  --task "prepare interview" \
  --json

link add writes project-local metadata under .holoself/, detects agent platforms, generates .holoself/BOOTSTRAP.md, and injects bounded startup pointers into detected instruction files after confirmation. It does not copy canonical self files. See Activated project links.

For verified MCP-capable clients, preview and activate typed on-demand access after linking:

holoself mcp configure --project C:/work/my-project --dry-run
holoself mcp configure --project C:/work/my-project --yes

First confirm that holoself --version works in the environment used by the client. The client starts holoself mcp as a local STDIO subprocess for that project. It is not a service. The explicit link remains authority; BOOTSTRAP/skill/CLI remain the fallback. See Local MCP integration.

Three distinct delivery modes

Every mode begins with the same project link and stays within its lens and privacy policy. The difference is how bounded context reaches the consumer:

flowchart LR
    L[Project link<br/>.holoself/link.yaml] --> B{Bounded selection<br/>lens · task · privacy}
    B --> M[Local MCP<br/>on-demand tools]
    B --> A[Startup instructions<br/>BOOTSTRAP + CLI]
    B --> X[Reviewed snapshot<br/>portable, may become stale]

    classDef authority fill:#10231d,color:#fffaf4,stroke:#245f50,stroke-width:2px
    classDef policy fill:#dceee3,color:#10231d,stroke:#245f50,stroke-width:2px
    classDef mode fill:#fffaf4,color:#10231d,stroke:#9be5c1,stroke-width:2px
    class L authority
    class B policy
    class M,A,X mode

• Metadata project link — recommended: link add|status|remove|setup|activate|deactivate|repair|doctor --project ... creates .holoself/link.yaml, activates configured startup pointers, and maintains local index, proposal, and report directories.
• Local MCP — preferred interaction where verified: the agent client launches Holoself on demand and calls bounded typed tools; this still requires the metadata link and coexists with startup instructions.
• Snapshot: export or context --snapshot creates reviewed generated context for portable or sandboxed use. It is not live and can become stale.
• Legacy live mount: link --target ... creates a filesystem symlink/junction from project .holoself to complete data root. It remains compatibility-only.

Never substitute one mode for another without reviewing privacy exposure. Startup adapters configure instruction pointers; packet formatters only change output framing. Generated files do not prove an application discovered them. See Runtime adapters. See Link or export?.

Common workflows

# Inspect the validated lens vocabulary and project context
holoself lens list --root C:/private/my-self
holoself context --project C:/work/my-project --lens career --format packet --adapter claude

# Produce non-mutating ownership/conflict recommendations
holoself analyze all --project C:/work/my-project

# Propose reusable knowledge, then review it
holoself propose --project C:/work/my-project --claim "..." --evidence "..." --source-file notes.md
holoself proposals show <id> --project C:/work/my-project
holoself proposals approve <id> --project C:/work/my-project --yes

# Build and query disposable local indexes
holoself index rebuild --project C:/work/my-project
holoself search "regulated AI" --project C:/work/my-project --federated

Approval prints target, evidence, affected files, and proposed diff before writing. Automation must pass --yes explicitly.

Documentation

• Documentation map
• Whole-person context
• Ownership
• Lenses and privacy
• Proposal review
• Context efficiency and receipts
• Knowledge lifecycle
• CLI reference
• Local MCP integration
• Common use cases
• MCP tools
• Threat model
• Status and roadmap
• Privacy policy
• Workbench guided tour
• Workbench architecture and trust boundary

Development

npm test
npm run audit:package
node bin/holoself.mjs --help

Public package paths contain code, schemas, templates, synthetic defaults, and documentation only. Private profile, context, topics, reference material, and local contribs must remain outside this repository.