Every new session, your agent relearns your stack from scratch. It greps for a framework, opens package.json, walks the folder tree, guesses the deploy flow, asks which database you use. You've answered these questions a hundred times. The answers don't change between Tuesday and Wednesday — but the agent's memory does.
The Technical Profile fixes that. It's a small, structured record of how a project is built that lives with the project's operational state. An agent reads it in one call and skips the scan. It's available in Brain OS Cloud via the connector.
The one move: read before scan
The whole feature is a habit: before exploring a codebase, read its Technical Profile.
You get back a compact object — frontend, backend, database, hosting, deploy flow, key commands, known gaps — plus how fresh it is (last_verified_at) and how much to trust it (confidence, source). If it's there and current, the agent has what it needed without reading a single source file. If it's missing or stale, the tool says so, and the agent scans (once) and writes the profile back.
Two tools, that's the whole surface:
| Tool | Direction | Who can call it |
|---|---|---|
technical_profile_read(entity_id) | Read the profile (or learn there isn't one) | Anyone — local session or connector |
technical_profile_update(entity_id, {...}) | Write/refresh the canonical profile | Local session only (see Governance) |
The read is cheap and always allowed. The write is a governed, canonical action.
What it is (and isn't)
The Technical Profile is structured reference state, not a narrative. It never goes in free-text fields like a progress log — it's a typed object with named sections, so an agent can pull exactly the slice it needs (just the deploy flow, just the test command) without parsing prose.
- It answers "how is this built?" — not "what's the status?" (that's the entity's
next_move/momentum) and not "what did we decide?" (that's decisions). - It's per-project. Each tracked project carries its own profile.
- It's meant to be read first and often, written rarely — you verify the stack once, then every future session rides on it until something real changes.
Schema reference
A profile has four content sections plus a small metadata header.
Metadata header
| Field | Type | Meaning |
|---|---|---|
schema_version | 1 | Schema version (currently always 1). |
last_verified_at | YYYY-MM-DD | When the profile was last confirmed against reality. Drives the staleness flag (>45 days → "consider refreshing"). |
confidence | "high" | "medium" | "low" | How much to trust it. low on a freshly initialized profile; high once verified against the real repo. |
source | "manual" | "repo_scan" | "agent_verified" | How it was populated. manual = typed in; repo_scan = generated from the code; agent_verified = an agent read the code and confirmed. |
tech_stack
Named buckets of technologies. Every field is an optional string[] — include only what applies.
infrastructure
How and where it runs.
| Field | Type | Notes |
|---|---|---|
environments | string[] | e.g. ["local", "staging", "production"]. |
cloud_services | string[] | Managed services in use. |
domains | string[] | Public/app domains. |
data_stores | string[] | Concrete stores and what lives in them. |
queues_or_jobs | string[] | Background workers, cron, queues. |
deployment_flow | string | One sentence: how a change reaches production. |
migrations | string | How schema/data migrations run. |
secrets_required | string[] | Names only, never values — e.g. "STRIPE_SECRET_KEY". See Governance. |
architecture_summary
The mental model.
| Field | Type | Notes |
|---|---|---|
one_liner | string | What this system is, in a sentence. |
key_flows | string[] | The handful of paths that matter (e.g. "signup → email verify → session"). |
boundaries | string[] | Hard lines the system enforces. |
important_constraints | string[] | Rules an agent must respect. |
known_gaps | string[] | Open weaknesses / not-yet-done. |
repos
An array — one entry per repo/package in the project.
| Field | Type |
|---|---|
path | string |
package_manager | string |
main_commands | string[] |
deploy_command | string |
test_command | string |
Example
A generic project — call it Acme Store, a small e-commerce app.
Writing the profile (local session)
Reading it back (any session, including a connector)
Next session, instead of exploring, the agent calls:
…and immediately knows it's a Next.js + Supabase + Stripe app on Vercel, that money is in integer cents, that order state only changes via webhooks, and that there's a known oversell race — before touching a single file. When the agent later notices the payments provider changed, it refreshes the profile and last_verified_at moves forward.
Governance & safety
The Technical Profile follows the same trust boundary as the rest of Brain OS.
- Canonical writes are local-only.
technical_profile_updatefrom a connector (ChatGPT, Grok, Claude.ai, Cursor) is rejected withconnector_write_rejected. A connector can propose a profile change through the memory candidate queue (memory_ingest), where it waits for your approval — it never edits the canonical profile directly. Reads are open to everyone. - Secrets are names, never values.
secrets_requiredlists env-var names so an agent knows what a project needs — not the credentials themselves. The write path scans the whole payload and refuses anything that looks like a real secret. Nothing in a Technical Profile is a credential. - Staleness is surfaced, not hidden. A profile older than 45 days reads back with a "consider refreshing" note, so an agent knows to re-verify before trusting an aging record instead of acting on drift.
When to use it
- Starting a session on an existing project → read the profile first; scan only if it's missing or stale.
- Onboarding a new agent or tool → the profile is the fastest way to hand over "how this is built."
- After a real infrastructure change (new database, new host, changed deploy flow) → refresh the profile from a local session so every future session inherits the truth.
The payoff compounds: verify once, and every agent across every session and every connected tool stops relearning your stack.
Stop re-explaining your stack
Technical Profile ships with Brain OS Cloud — connect your AI tools and give every session the same structured memory of how your projects are built.
Join the beta