project-bedrock: A project cockpit for your AI agents.

Every session starts with context.

Every important decision leaves a trail.

Every session leaves the project smarter.

robotaitai

AI can write code fast.

What it does not do well by default is leave behind clear, shared project understanding.

Decisions disappear into chat history.
Architecture gets rediscovered.
New sessions start from zero.
And the next developer, human or AI, has to figure out again what changed, where, and why.

Project Bedrock turns your repo into a project cockpit for AI agents: what we know, what matters now, and what to load next.

It works like the operating discipline of a strong team lead:

• every session starts with context
• every important change leaves a trail
• stable knowledge gets written down where the next developer can find it
• the project becomes easier to understand over time, not harder

With one command, your project gets:

• PROJECT-SHAPED MEMORY for architecture, decisions, conventions, and domain context
• A SMALL WORK LAYER for current focus, open loops, and recommended next actions
• PROJECT-LOCAL integration for Claude Code, Cursor, and Codex
• lightweight git-friendly markdown that LIVES WITH THE REPO
• HTML, graph, and Obsidian-ready VIEWS for human inspection

Under the hood, it is just markdown files and a CLI.
No database. No server. No hosted backend. No black box.

The result: your AI developers stop behaving like disconnected sessions, and start behaving more like a team.

📦 Install

Option A — let your agent do it (no pip knowledge needed):

Paste this into Claude Code, Cursor, or any capable agent:

Install the `project-bedrock` CLI on this machine so `bedrock --version` works. Handle Python and pipx installation if missing. Fix any errors along the way. Don't stop until it's working.

The agent detects your OS, installs Python + pipx if needed, installs the package, and verifies it. Works on macOS, Linux, and Windows.

Option B — one-liner (Mac / Linux):

curl -fsSL https://raw.githubusercontent.com/robotaitai/project-bedrock/main/install.sh | bash

Auto-detects uv → pipx → pip in that order.

Option C — pick your tool:

uv tool install project-bedrock   # fastest, isolated (recommended)
pipx install project-bedrock      # isolated
pip install project-bedrock       # classic

PyPI: project-bedrock  ·  CLI: bedrock  ·  alias: agent-knowledge (deprecated)

🚀 Quick Start

1. Initialize the project (run once in your project folder):

cd your-project
bedrock init

2. Onboard your agent — paste this into chat:

Read AGENTS.md and ./bedrock/STATUS.md, then onboard this project.

That's it. The agent writes stable knowledge into Memory/, current priorities into Work/, and every future session starts with better context automatically.

💾 Storage Modes

By default, knowledge lives inside the repo (git-tracked). Curated knowledge is committed normally; noisy subfolders are gitignored.

# Default: in-repo (recommended)
bedrock init

# External: knowledge outside the repo (not committed)
bedrock init --external

# Convert external -> in-repo later
bedrock migrate-to-local

🧠 How It Works

Think of the vault as your team's shared project cockpit. The goal is not more documentation for agents to blindly read. The goal is less context, loaded better.

Project Cockpit

The rule: stable facts go into Memory/, current priorities go into Work/, and generated views stay in Views/. Imported or generated material is never canon by itself.

Memory Is Project-Shaped

Bedrock does not force every repo into the same documentation template.

• A robotics repo may organize Memory around perception/, navigation/, localization/, and safety/
• A SaaS repo may organize Memory around frontend/, backend/, auth/, billing/, and data/
• Bedrock itself may organize Memory around product/, runtime/, cli/, integrations/, memory-model/, and views/

🔌 Project-Local Integration

The project carries everything it needs. Claude Code, Cursor, and Codex all get integration installed automatically on init -- hooks, runtime contracts, and slash commands. No global config.

Platform & Tool Support

 Auto-installed on init -- hooks fire automatically, slash commands active, bedrock doctor validates health.    AGENTS.md installed when .codex/ detected -- agent loads memory context, no automated hooks.

CI matrix: ubuntu-latest + macos-latest, Python 3.9 / 3.12 / 3.13. Windows: Git Bash auto-detected; forward-slash paths and UTF-8 subprocess encoding fixed in v0.4.0.

⚡ Session Lifecycle

Hooks fire automatically -- zero manual intervention:

The agent reads STATUS.md, Memory/PROJECT.md, and Work/NOW.md at the start of every session, with no prompting required.

💬 Slash Commands

These are how the team writes to the logbook. Both work in Claude Code and Cursor -- init installed them.

A developer should never finish a session without updating the cockpit. The point is not to save everything. The point is to save the next useful context.

🩺 Integration Health

bedrock doctor

Reports whether all integration files are installed and current. If anything is stale or missing, doctor tells you exactly what to run.

🔮 Obsidian-Ready

Each project's ./bedrock/ is a valid Obsidian vault on its own. But the real payoff is ~/agent-os/projects/: every project you've ever run init in is registered there. Open that folder in Obsidian and you have a unified vault across all your teams' projects -- backlinks, graph view, and full-text search spanning every codebase you manage.

One window. Every team.

bedrock export-canvas
# produces: bedrock/Views/graph/knowledge-export.canvas

Obsidian is optional. Works without it too.

🛠️ Commands

More

• Static site export -- bedrock view builds an interactive HTML site from your vault
• Automatic capture -- every sync event is recorded as lightweight evidence
• Progressive retrieval -- agents load only the branches they need
• Clean web import -- import a URL as cleaned markdown evidence
• Project history -- lightweight event log auto-backfilled from git
• Keeping up to date -- pip install -U project-bedrock + bedrock refresh-system
• Migrating from agent-knowledge-cli -- 3-step migration to project-bedrock and the bedrock CLI
• Custom knowledge home -- change where ~/agent-os/ lives
• Troubleshooting -- common issues and fixes
• Platform support -- macOS, Linux, Windows, Python 3.9+
• Development -- contributing and running tests

Star History