---
node_id: n_64dbf7878f05362337a6cda6
name: Ideaspace Protocol
kind: repo
canonical_url: /repos/n_64dbf7878f05362337a6cda6
---

# Ideaspace Protocol

[![CI](https://github.com/IdeaSpaces-xyz/ideaspace-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/IdeaSpaces-xyz/ideaspace-protocol/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@ideaspaces/protocol?label=npm)](https://www.npmjs.com/package/@ideaspaces/protocol)
[![Node.js](https://img.shields.io/node/v/@ideaspaces/protocol)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Status: provisional](https://img.shields.io/badge/protocol-provisional-orange.svg)](#status)

> The platform-neutral **shape** of a knowledge repo. An agent that knows this shape can inhabit any conformant space — orient, navigate, work — with no bespoke instructions.

[Explore this repo as an Ideaspace](https://ideaspaces.xyz/spaces/n_64dbf7878f05362337a6cda6) · [Install from npm](https://www.npmjs.com/package/@ideaspaces/protocol) · [Read the spec](SPEC.md) · [See the skills](SKILLS.md)

An **ideaspace** is a folder of Markdown under git: knowledge accumulates as `.md` files, how-to-work lives in an `_agent/` folder, and git carries identity and history. This repo defines that shape — the spec, a machine-readable schema, a reference implementation, and a conformance kit — in one place, so any tool or agent can read and write ideaspaces predictably.

It is **not a data format for retrieval**. It is an *inhabitation contract*: shape + identity + conformance, plus the verbs to work a space. The shape is fixed so it is predictable — drop a conformant agent into a conformant space and it already knows where to look.

## Why this exists

Agent context is usually trapped in a product, a prompt, or a transcript. A fixed repository shape makes the knowledge and the agreement for working with it portable. People keep ordinary files and full history; agents get a predictable way to orient and act without every repository inventing its own instructions.

## Experience the protocol

This repository is both the definition and a conformant example. [Browse it as a public Ideaspace](https://ideaspaces.xyz/spaces/n_64dbf7878f05362337a6cda6), navigate the same Markdown as structured knowledge, ask it questions with your own agent, or copy it into your account. Its [root `_agent/` contract](https://github.com/IdeaSpaces-xyz/ideaspace-protocol/tree/main/_agent) dogfoods the protocol it defines.

## What's here

| Path | What |
|---|---|
| [`SPEC.md`](SPEC.md) | **Normative.** The shape, identity, two layers, conformance (MUST/SHOULD). |
| [`SKILLS.md`](SKILLS.md) | **Normative.** The ability layer — the verbs (orient, understand, capture, reflect, share) that ride on the shape. |
| [`schema/`](schema/) | Language-neutral contract — frontmatter, `_agent/`, Change/surface state, structured Content awareness, and local workspace handles. |
| [`src/`](src/) | Reference TypeScript implementation — frontmatter, contract/path reads, structured awareness assembly/rendering, workspace handles, git state, drift, and the skill catalog. |
| [`conformance/`](conformance/) | A reference conformant space and a validator that checks a space (and an implementation) against the spec. |
| [`VERSION`](VERSION) | Current spec version. Tools declare conformance to a version. |

## Concepts in 30 seconds

- **Position.** Every directory is a position, presenting as *summary → surface → children*. Its surface — a `README.md`, a repo's root README, or a lone `.md` file — says what it is, for everyone. Depth is elaboration: a child answers "what do you mean?" about the surface above it.
- **Two kinds of content.** Plain `.md` files are *knowledge*; the `_agent/` folder is *agent context* (how to work here). Everything not underscore-prefixed is knowledge.
- **The `_agent/` contract.** `foundation.md` (root handshake), `guide.md`, `purpose.md`, `now.md`, `next.md`, and optional `schema.md` (the shape of Notes in the folder — guidance, not validation). Give it a good surface: loaded at depth 0, with depth on demand.
- **Fractal.** `_agent/` can appear at any position and composes along the path: general at the root, specific as you descend.
- **Identity in git.** The author is the person; an agent that helped adds a `Co-authored-by:` trailer. Provenance rides in git, not in a file's frontmatter.

The full, normative version is [`SPEC.md`](SPEC.md).

## Using the reference library

```bash
npm install @ideaspaces/protocol
```

```ts
import {
  assembleContentAwareness,
  renderContentAwareness,
} from "@ideaspaces/protocol";

const manifest = await assembleContentAwareness({ position: process.cwd() });
if (!manifest) throw new Error("No ideaspace contract resolves here");

// Render all canonical sections, or select a subset for harness placement.
const text = renderContentAwareness(manifest);
const stable = renderContentAwareness(manifest, {
  sections: ["position", "now", "tree", "contract", "skills"],
});
```

Local harnesses can also read neutral, unrendered workspace handles without
assigning protocol-level home/mount/POV roles:

```ts
import {
  readRootHandle,
  readWorkspaceRepositories,
} from "@ideaspaces/protocol";

const home = await readRootHandle(process.cwd());
const repositories = await readWorkspaceRepositories("../");
```

The TypeScript library is the *reference* implementation, not the only one. Other languages conform to the language-neutral core — [`SPEC.md`](SPEC.md) + [`schema/frontmatter.schema.json`](schema/frontmatter.schema.json) + the conformance fixtures.

## Conformance

A tool that claims to inhabit ideaspaces follows the **MUST/SHOULD** in [`SPEC.md`](SPEC.md#conformance) and declares the spec version it targets. The [`conformance/`](conformance/) kit makes that testable.

## Ecosystem

The protocol owns portable shape and ability semantics. Each integration keeps its own tools, permissions, placement, and lifecycle behavior.

| Project | Role |
|---|---|
| **Ideaspace Protocol** | Spec, schema, reference library, skills, and conformance kit — this repository. |
| [Claude Code plugin](https://github.com/IdeaSpaces-xyz/claude-code-plugin) | The recommended local-first path for Claude Code and Cowork; includes the Ideaspace skills and MCP tools. |
| [Pi extension](https://github.com/IdeaSpaces-xyz/pi-is-space) | Protocol-backed awareness, capture, and sync in Pi. |
| [CLI](https://github.com/IdeaSpaces-xyz/cli) | Create, publish, clone, push, pull, and automate spaces from the terminal. |
| [SDK](https://github.com/IdeaSpaces-xyz/sdk) | Keeper transport types and Pi-to-Keeper translation; not a protocol compatibility layer. |
| [IdeaSpaces](https://ideaspaces.xyz) | Optional hosting for sharing, access control, public exploration, and search across spaces. |

## Status

**v0.4.7 — early and provisional.** The spec, skills, structured Content awareness, portable workspace handles, and reference library are in place; the schema is provisional and expected to evolve (notably the open `attached_to` type vocabulary). Pin a version and expect changes before 1.0.

## Develop

```bash
npm ci
npm run build      # build the reference library (ESM → dist/)
npm test           # run the suite (vitest)
npx tsc --noEmit   # typecheck
```

See [`_agent/guide.md`](_agent/guide.md) for how to work in this repo.

## License

[MIT](LICENSE).

## Contents

- **conformance/**
- **schema/**
- **scripts/**
- **skills/**
- **src/**
- [CLAUDE](/n/n_dde1128d4ca03a1bfb717f53.md)
- [The Skills Layer](/n/n_f4c2c9573efbb6c197ea95ce.md) — The companion to SPEC.md: the spec gives an agent awareness of an ideaspace; skills give it the ability to work there. The per-session loop is arrive → orient → inspect → act → capture → push/pull → reflect. Shared skill substance lives in this protocol's skills/ catalog and is distributed to each surface; thin surface entrypoints adapt it to their native tools. Daily intent skills are is-orient, is-capture, is-push, is-pull, and is-reflect, with lifecycle, shaping, and reference skills alongside them.
- [The Ideaspace Spec](/n/n_29767429bcb12074f4788729.md) — A simple, shareable, traceable piece of brain — and the fixed, platform-neutral shape that makes it so. Knowledge in `.md` files, how-to-work in `_agent/`, git carries identity and history. Any agent that knows the shape can inhabit any conformant space. The base layer gives awareness; skills give ability.