p2-kit turns a P2 into a portable, human-readable brain for AI agents and teams.

The premise is simple: a P2 can be more than a publishing surface. It can be a hosted, permissioned, inspectable memory layer that any capable agent can load, use, update, and hand off. A brain can be private to one person, shared read-only with a team, or collaboratively written by multiple people and agents. Instead of tying long-term context to one vendor, runtime, or local machine, the "brain" is a P2 URL plus a small set of conventions.

P2 already has useful properties for agent memory:

• Hosted: available from anywhere an authorized agent can reach it.
• Portable: usable across agents, sessions, and tools.
• Readable: humans can inspect and correct the memory directly.
• Social: shared brains can give teams a common working context.
• Permissioned: access can follow existing P2 and WordPress.com controls.
• Durable: important decisions, context, and artifacts do not disappear when a chat ends.

p2-kit is not trying to make P2 into a vector database. Its strength is that memory remains understandable, editable, linkable, and socially legible.

A brain is a P2 with a protocol.

At minimum, a brain should have:

• a Brainstem page, written as normal WordPress blocks, that explains the brain's purpose, owner, scope, rules, and indexes
• a Memory page that stays compact and current with recent and important memory
• a local P2-BRAIN.md pointer in each project that should use the brain
• memory posts for decisions, preferences, project state, artifacts, meeting notes, and unresolved questions
• summaries that compact recent activity into useful working context
• source links back to Slack, Linear, GitHub, Zendesk, P2s, files, screenshots, or other evidence
• hygiene rules for stale context, sensitive content, confidence, write modes, and publish behavior

Agents can then be told:

Use this P2 as your brain.

The agent loads the Brainstem, reads the Memory page, searches relevant posts, performs the task, and writes useful new context back to the brain.

For project work, the local P2-BRAIN.md file is the discovery hook. It tells an agent which hosted brain to load without requiring the user to paste the P2 URL into every session.

Different P2s can act as different brains:

• Personal brain: private work memory, preferences, goals, recurring context, review evidence
• Project brain: decisions, current state, open questions, milestones, artifacts
• Team brain: rituals, norms, updates, shared references, operating context
• Shared reference brain: read-mostly context that many agents can load, with a small set of maintainers
• Multiplayer brain: collaboratively written context where team members and their agents can draft or publish memory under shared rules
• Design brain: snaps, visual explorations, feedback, rationale, iterations
• Review brain: self-feedback, accomplishments, impact evidence, growth notes
• Incident brain: timeline, decisions, remediation, follow-ups, learnings

Swapping brains should be as simple as pointing the agent at a different P2 and loading that brain's Brainstem.

The same protocol works for teams. A shared brain lets team members and their agents work from the same context instead of each person rebuilding it in separate chats.

Useful shared-brain modes:

• Read-only shared brain: many people and agents can load/search context, but only maintainers write. Good for team norms, project state, onboarding, and canonical decisions.
• Draft-only shared brain: many agents can create proposed memories as drafts, while humans review/publish. Good for early team use where trust and format are still developing.
• Multiplayer write brain: multiple people and agents can publish under explicit rules. Good for high-trust teams, fast-moving projects, incidents, or design/product rituals where shared context needs to stay current.

Shared brains need clearer rules than personal brains: who owns the Brainstem, who can publish, when to update an existing memory instead of adding a new post, and how to handle conflicting context. The Brainstem should make the audience and write mode explicit.

For now, p2-kit should assume that creating the P2 itself is a human-in-the-loop setup step.

The current context-a8c tools can discover P2s and create or update content on existing WordPress.com/P2 sites, but they do not expose a tool for provisioning a brand-new P2. Internal docs point Automatticians to the MC P2 tool for that step:

https://mc.a8c.com/tools/p2/

Suggested setup flow:

1. Open the MC P2 tool.
2. Create a new internal P2 for the brain.
3. Choose a clear URL, such as:
   • shauns-brain.wordpress.com
   • p2-kit-brain.wordpress.com
   • team-name-brain.wordpress.com
4. Keep the P2 private unless there is a specific reason to share it.
5. Add the intended human owner and any collaborators.
6. Give the agent the P2 URL.
7. The agent verifies access and creates the initial published Brainstem and Memory pages.
8. The agent inspects the default About page and replaces it automatically if it is generic.
9. The agent publishes a first initialization post when the P2 is new/empty.
10. The agent writes a local P2-BRAIN.md pointer file in the current project.

For a first version, a skill can help by opening the MC tool for the user, preparing the recommended site name and form values, then verifying the created P2 and publishing the initial setup content once the user provides the URL.

p2-kit should not try to silently provision P2s. Brain creation changes audience, permissions, and long-term memory boundaries, so it should stay explicit.

The first version should be skills-first. Skills define the behavior and conventions; implementation can use context-a8c where available.

0. p2-brain-init

   • Explain how to create a new brain P2.
   • Open or link to the MC P2 tool.
   • Recommend a brain name, URL, privacy posture, and owner/collaborators.
   • Accept an existing P2 URL and skip the setup flow.
   • Create and publish the initial Brainstem page as WordPress blocks when it is missing.
   • Create and publish the initial Memory page when it is missing.
   • Replace default About page content without overwriting customized About content.
   • Publish the first brain-init post when no prior init post exists and there are no unrelated published posts.
   • Save a local P2-BRAIN.md pointer file for future agents.
   • After the user creates the P2, verify access and reconcile the full setup.
   • When P2-BRAIN.md already exists, use it and still reconcile About and the first post.

1. p2-brain-load

   • Read local P2-BRAIN.md when present to discover the default brain.
   • Given a P2 brain URL, load the Brainstem.
   • Identify active indexes and recent summaries.
   • Search task-relevant memory.
   • Produce a compact working-memory summary for the current agent session.

2. p2-brain-memory

   • Read and maintain the primary Memory page.
   • Keep recent and important memory compact, current, and cited.
   • Create supporting memory posts when a detail needs its own durable record.
   • Follow the Brainstem write mode; do not bake in a project-wide draft preference.

3. p2-brain-hooks

   • Install local agent hooks that automatically publish session memory.
   • For Claude Code, configure SessionStart, PostToolUse, Stop, and SessionEnd hooks.
   • Use a non-interactive child agent to publish a session-summary post and update Memory.
   • Treat hook setup as explicit user permission to publish hook-derived session memory.
   • Support a manual rehearsal that publishes the same kind of session summary and Memory update from the active session.

4. p2-brain-write

   • Save new durable context back to the brain.
   • Choose whether to update the Memory page, update an existing memory post, or create a new memory post.
   • Include source links, confidence, status, and follow-ups.
   • Follow the Brainstem write mode.

5. p2-brain-handoff

   • Summarize current work so another agent can continue.
   • Capture what changed, what matters, open questions, next steps, and relevant links.
   • Write a durable handoff post or update an existing project log.

• p2-brain-search: query prior memory and return cited context
• p2-project-log: maintain a project-specific running log
• p2-team-update: draft team updates from Slack, GitHub, Linear, Zendesk, and P2 context
• p2-snap: package visual design snapshots with rationale and feedback prompts
• p2-self-feedback: collect review evidence and draft self-feedback
• p2-performance-review: structure review input with evidence and examples
• p2-decision-record: capture durable decision records

The Memory page is the primary working-memory surface for an agent. It should be a published page titled Memory with slug memory.

The Memory page is not a full archive. It is the compact context layer an agent can read after the Brainstem. It has two required sections:

• Short Term: active working set for current projects, recent changes, open loops, and context likely to change soon.
• Long Term: durable facts, decisions, preferences, stable project context, and canonical links that should survive across sessions.

Agents should keep the Memory page concise. Short Term is volatile and should be pruned or promoted. Long Term is curated and should change more slowly. When a memory needs detail, discussion, or source-heavy context, create or update a separate memory post and link it from the Memory page.

The model is intentionally small:

• Brainstem: always-read operating instructions for the brain.
• Memory page: always-read compact working context.
• Supporting memory posts: deeper records opened only when relevant.

This keeps token use predictable while preserving enough structure for durable context. The Memory page should act like an agent-maintained table of contents plus working set, not a full transcript.

Promotion rules:

1. Capture active context in Short Term while it is useful for the current thread of work.
2. Promote to Long Term only when it is likely to matter across sessions, agents, or projects.
3. Link to supporting memory posts for decisions, handoffs, project logs, artifacts, and source-heavy summaries.
4. Remove or archive stale Short Term items once they are resolved, superseded, or promoted.
5. Preserve source links, confidence, and dates for Long Term items whenever possible.

Publishing is core to the brain: memory needs to be available to future agents. Draft/review is a write mode a human or team can choose, not a global default baked into the protocol.

The setup flow creates a few different content surfaces with different jobs:

• Brainstem page: canonical agent protocol.
• Memory page: compact current context.
• About page: human-facing description of the P2 brain.
• First post: human-facing launch note in the P2 timeline.

New P2s often have a generic About page. p2-brain-init should inspect it and replace it automatically when it is missing, empty, or clearly generic. It should not overwrite a customized About page unless the user explicitly confirms.

The first post should be published after Brainstem and Memory exist, but only when no prior initialization post exists and there are no unrelated published posts, or when the user explicitly asks for it. Brainstem, Memory, and About are setup pages and do not count against creating the first post. It should be more narrative than procedural:

Title: The brain comes online

Type: brain-init
Status: current
Date: 2026-05-11
Confidence: high
Source: p2-brain-init

This P2 is now a portable brain: a place where agents can leave durable context instead of letting every useful decision, preference, and handoff disappear when a chat window closes.

The first job is simple. Remember the shape of the work. Keep the small, current stuff close at hand in Memory. Put the durable stuff into posts that humans can read, correct, and link to. Let future agents arrive here, read the Brainstem, check Memory, and continue with less ceremony.

The core pieces are in place: Brainstem holds the operating instructions, Memory holds the short-term and long-term working context, and future posts will capture decisions, handoffs, project logs, summaries, preferences, and artifacts.

This is not meant to be a hidden database. It is meant to be a shared surface: hosted, searchable, inspectable, and portable across agents.

Next, add the first useful memories and install hooks if this project should publish session summaries automatically.

Brainstem: <Brainstem URL>
Memory: <Memory URL or pending>

Use categories for broad content families and tags for filtering. The first initialization post should use categories Brain and Memory, with tags p2-brain and brain-init. Session-summary posts should use categories Brain and Summaries, with tags p2-brain, session-summary, and a project-specific tag when known.

p2-brain-init is reparative. Running it again should not stop just because Brainstem and Memory exist. It should always check the full setup surface: Brainstem, Memory, About, first post, taxonomy, and P2-BRAIN.md.

Hooks make the brain useful without relying on the agent to remember to write memory manually.

For Claude Code, p2-kit installs local hooks into .claude/settings.local.json:

• SessionStart: add a short reminder to load P2-BRAIN.md, Brainstem, and Memory.
• PostToolUse: mark the session dirty after meaningful file, shell, or write-like MCP activity.
• Stop: before the agent fully stops, run a non-interactive child claude -p process that publishes memory.
• SessionEnd: fallback publisher/outbox writer if the Stop hook did not complete.

The Stop hook is the important part. It receives the Claude transcript path, session ID, current directory, and final assistant message. The hook starts a child agent with P2_KIT_HOOK_CHILD=1 to avoid recursion. That child reads P2-BRAIN.md and the transcript, publishes a session-summary post to the P2, updates the Memory page, records success under .p2-kit/state/, and exits.

The hook should publish, not merely remind. Hook setup is explicit user permission for automatic publication of session summaries and derived Memory updates. Sensitive memory still requires care: ask during the live session when needed, and omit unresolved sensitive details from hook output.

Claude Code is the first supported hook target because its hook payload includes the fields p2-kit needs. Codex hook support should be treated as experimental until verified in the user's current Codex build.

For testing, the same write path can be rehearsed on demand from an active session: publish one session-summary post from the current conversation, update the Memory page, and report both URLs. That validates the P2 write behavior and taxonomy. It does not prove the installed hook fired; the real hook test is to dirty a Claude Code session, let it stop, and confirm that the child claude -p run created or updated the session summary and Memory.

Memory should be structured enough for agents and readable enough for humans.

# Decision: Use P2 as the first brain backend

Type: decision
Project: p2-kit
Status: accepted
Date: 2026-05-08
Confidence: high
Revisit: 2026-08-01

## Context

The project needs a hosted, portable memory layer that agents can use across sessions.

## Decision

Use P2 as the first backend for agent brain memory.

## Rationale

P2 is hosted, permissioned, human-readable, linkable, and already part of the expected work environment.

## Source Links

- Initial project discussion

## Follow-ups

- Define the Brainstem format.
- Create the first three skills: load, write, handoff.

Use Type: brain-init for the first initialization post and Type: session-summary for automatic hook summaries.

Automatic session-summary posts should use the same structure:

# Session Summary: p2-kit - 2026-05-11

Type: session-summary
Project: p2-kit
Session ID: <agent session id>
Status: current
Date: 2026-05-11
Confidence: high
Source: agent transcript

## Summary

What changed and why it matters.

## Decisions

- Durable decisions made during the session.

## Changes

- Files, P2 posts, tickets, PRs, or other artifacts touched.

## Open Loops

- Follow-ups for the next agent or session.

## Memory Updates

- Short Term: active context to keep fresh.
- Long Term: durable context promoted from the session.

Suggested taxonomy:

• brain-init: categories Brain, Memory; tags p2-brain, brain-init
• session-summary: categories Brain, Summaries; tags p2-brain, session-summary, project tag
• decision: categories Brain, Decisions; tags p2-brain, decision, project tag
• handoff: categories Brain, Handoffs; tags p2-brain, handoff, project tag
• project-log: categories Brain, Projects; tags p2-brain, project-log, project tag
• preference: categories Brain, Preferences; tags p2-brain, preference
• artifact: categories Brain, Artifacts; tags p2-brain, artifact, project tag

Every brain should have a canonical Brainstem page. The Brainstem tells an agent how to use the brain, and should be stored as normal WordPress blocks rather than raw Markdown. Agents should read its rendered or plaintext form so block markup does not become working-memory noise.

# Brainstem

Brain name: Shaun Work Brain
Owner: Shaun
Audience: Private - Shaun only
Write mode: Owner-defined
Scope: Private work memory
Default behavior: publish the Brainstem during setup; follow write mode for ordinary memories
Primary indexes:
- Memory
- Active projects
- Decisions
- Preferences
- Review evidence

Rules:
- Cite sources for factual claims.
- Mark uncertain or inferred context clearly.
- Prefer updating existing memory over creating duplicates.
- Put active or changing context in Short Term.
- Promote durable cross-session context to Long Term.
- Link supporting memory posts when details or sources matter.
- Use brain-init for the first setup post.
- Treat review and HR content as sensitive.
- Follow the write mode before publishing to shared P2s.

Memory page standard:
- Short Term: active working context, recent changes, open loops, and information likely to change soon.
- Long Term: durable facts, decisions, preferences, stable project context, and canonical links.

Standard taxonomy:
- Categories: Brain, Memory, Projects, Decisions, Handoffs, Artifacts, Preferences, Summaries
- Tags: p2-brain, brain-init, brainstem, memory, short-term, long-term, session-summary, decision, handoff, project-log, artifact, preference, summary

Hook policy:
- Session summaries: auto-publish from configured hooks.
- Memory updates: auto-publish when derived from the same session summary.
- Sensitive memory: ask during the session; if unresolved, omit from hook output.
- Shared brains: follow the brain write mode.

Projects that use a P2 brain should include a small P2-BRAIN.md file at the project root. It should contain only the brain pointer and operating instructions, not private memory content.

# P2 Brain

This project uses a P2 as portable agent memory.

- Brain: Shaun's Brain
- Brain URL: https://shaunsbrain.wordpress.com/
- Brainstem: https://shaunsbrain.wordpress.com/brainstem/
- Memory: https://shaunsbrain.wordpress.com/memory/
- Project: p2-kit
- Scope: p2-kit project memory, decisions, preferences, and handoffs
- Owner: Shaun Andrews
- Audience: Private - Shaun only
- Write mode: Defined by Brainstem; no project-level override
- Last verified: 2026-05-11

## Agent Instructions

1. Load the Brainstem before substantive work when project context, prior decisions, or owner preferences may matter.
2. Load the Memory page when it exists; it is the compact recent/important context layer.
3. Search the brain before assuming important context is missing.
4. Use the brain when the user asks to remember, save, hand off, continue, or explain prior decisions.
5. Follow the Brainstem write mode before creating or updating memory.
6. Cite source links and mark assumptions, inferences, and stale context.

The default behavior should be conservative:

• Publish the Brainstem during setup so future agents have canonical loading instructions.
• Follow the Brainstem write mode for ordinary memories.
• Always show the target P2 and intended audience before posting.
• For shared brains, show the write mode before creating or updating memory.
• Cite sources for factual claims.
• Separate facts, preferences, assumptions, and inferences.
• Mark stale or low-confidence context.
• Treat HR, performance, customer, and private-team information as sensitive.
• Prefer summaries and links over copying large private conversations.
• Ask before moving context from a private brain to a shared brain.
• In multiplayer brains, prefer updating canonical memory posts over creating competing versions.

The practical starting point is to define the protocol before building many workflows.

1. Write the first SKILL.md for p2-brain-init.
2. Define the required Brainstem fields.
3. Create a sample personal Brainstem page.
4. Create a sample project Brainstem page.
5. Create one private P2 manually through the MC P2 tool.
6. Add a P2-BRAIN.md pointer to one project.
7. Write p2-brain-load.
8. Implement p2-brain-memory.
9. Implement p2-brain-hooks.
10. Implement p2-brain-write.
11. Implement p2-brain-handoff.
12. Test the flow against one private P2:

• load the brain
• ask a task-specific question
• write a memory
• auto-publish a session summary from hooks
• produce a handoff
• start a new session and reload from the brain

p2-kit/
  README.md
  skills/
    p2-brain-init/
      SKILL.md
    p2-brain-memory/
      SKILL.md
    p2-brain-hooks/
      SKILL.md
      scripts/
        install-claude-hooks.mjs
        p2-brain-hook.mjs
    p2-brain-load/
      SKILL.md
    p2-brain-write/
      SKILL.md
    p2-brain-handoff/
      SKILL.md
  references/
    brain-protocol.md
    brainstem.md
    memory-posts.md
    safety-and-hygiene.md
    context-a8c.md
  examples/
    personal-brainstem.md
    project-brainstem.md
    decision-memory.md
    handoff-memory.md

• What is the minimum Brainstem needed for a useful first brain?
• Should memories be primarily posts, comments, or a mix?
• How should agents discover canonical index posts?
• How should shared brains handle conflicts when two agents update the same memory?
• How should stale memory be marked and revisited?
• What should be private by default?
• How much should the skills rely on context-a8c versus plain P2/WordPress.com APIs?
• Should the protocol support non-P2 backends later, or stay intentionally P2-native?

The first milestone is a working "brain loop":

1. An agent loads a P2 brain.
2. The agent performs useful work using that context.
3. The agent writes a durable memory back to the brain.
4. A different agent or later session can load the brain and continue with minimal explanation.

That loop is the core product.