project-bedrock 0.4.12

Shared memory foundation for AI development teams

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 — manual:

pip install project-bedrock        # or: pipx install project-bedrock

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.

What init does in one shot

Step	What happens
1	Creates ./bedrock/ as a real directory inside the repo (git-tracked)
2	Registers the project in ~/agent-os/projects/<slug>/ so every project shows up in one place -- open it in Obsidian for a unified cross-project vault
3	Adds noisy generated subfolders (Evidence/raw/, Views/site/, ...) to .gitignore automatically
4	Installs project-local integration for Claude Code and Cursor
5	Detects Codex and installs its bridge files if present
6	Bootstraps the project cockpit (Memory/, Work/, Views/) and marks onboarding as pending
7	Imports repo history into Evidence/ and backfills lightweight history from git

---

💾 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

	Folder	What goes here	Canon?
📘	Memory/	What the project knows -- stable, durable, project-shaped knowledge	Yes
🎯	Work/	What matters now -- current focus, next actions, open questions, risks	Yes
👁️	Views/	Human inspection views -- generated site and graph output	No
📅	History/	Legacy diary layer -- still supported	Yes
📎	Evidence/	Raw imports: docs, ADRs, PRs, screenshots -- captured context	No
📊	Outputs/	Legacy generated artifacts -- still supported	No

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.

Claude Code  .claude/

File	Purpose
settings.json	Lifecycle hooks: sync on SessionStart, Stop, PreCompact
CLAUDE.md	Runtime contract: knowledge layers, session protocol, onboarding
commands/memory-update.md	/memory-update slash command
commands/system-update.md	/system-update slash command
commands/absorb.md	/absorb <file/folder> slash command

Cursor  .cursor/

File	Purpose
rules/bedrock.mdc	Always-on rule: loads memory context on every session
hooks.json	Lifecycle hooks: sync on start, update on write, sync on stop/compact
commands/memory-update.md	/memory-update slash command
commands/system-update.md	/system-update slash command
commands/absorb.md	/absorb <file/folder> slash command

Codex  .codex/  (installed when detected)

File	Purpose
AGENTS.md	Agent contract with knowledge layer instructions

⚡ Session Lifecycle

Hooks fire automatically -- zero manual intervention:

Event	Claude Code	Cursor	What runs
Session start	SessionStart	session-start	bedrock sync
File saved	--	post-write	bedrock update
Task complete	Stop	stop	bedrock sync
Context compaction	PreCompact	preCompact	bedrock sync

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.

Command	When to use it
/memory-update	End of session, before logging off. The agent updates the project cockpit: stable facts in Memory/, current priorities in Work/, and a short summary of what changed.
/system-update	After upgrading project-bedrock. Refreshes hooks, rules, commands. Purely infrastructure -- never touches knowledge content.

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

Command	What it does
init	Set up a project -- one command, no arguments
sync	Full sync: memory, history, git evidence, index
ship	Validate + sync + commit + push
view	Build site and open in browser
doctor	Validate setup, integration health, note staleness

All commands

absorb · search · export-html · export-canvas · clean-import · refresh-system · backfill-history · compact · migrate-to-local · init --external

All write commands support --dry-run and --json. Run bedrock --help for the full list.

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