Turn your agents into experts

Build a small knowledge graph that gives a coding agent the specific context required for one real task. Then use the result of that task to improve the graph.

This guide follows one repeatable loop:

Model → Connect → Flash → Work → Review → Refine

At the end, your agent will flash a target Module and receive the complete foundation-first context required to work in that domain.

Before you start

You need:

• The Socra CLI and Cortex namespace installed.
• A configured coding agent or terminal that can run Cortex commands.
• One real task that depends on knowledge specific to your organization.
• Permission to create Modules in your Account.

If Cortex is not connected to your coding agent, follow Coding agents.

Use this guide with an agent

Give your coding agent the Markdown version of this page:

https://workspace.socra.com/docs/cortex/guides/turn-agents-into-experts.md

Then ask:

Read this guide and help me model one domain in Cortex. Inspect existing Modules before proposing anything. Show me the exact Module content and dependencies, and wait for my approval before creating or updating a Module.

The engineer remains the author and approver. The agent can inspect, propose, and verify the graph, but it must not publish knowledge that the engineer has not approved.

Choose one expert outcome

Start with a task where a capable coding agent still needs knowledge that it cannot reliably recover from the repository.

For example, suppose the agent must add partial refunds to a billing service. The repository can show how the service works today, but it might not explain two organization-specific decisions:

• All monetary values use integer minor units.
• A refund must reference a settled charge, and cumulative refunds must not exceed the settled amount.

Define the observable outcome before creating a Module:

When the agent works on refunds, it retrieves both decisions, verifies the current implementation, and produces a change that preserves them.

Do not begin by importing a repository, handbook, or architecture document. Begin with the smallest body of knowledge that changes how the agent should perform the task.

Inspect the existing graph

Map the knowledge basin:

socra cortex map

Search for Modules that might already own the relevant knowledge:

socra cortex module search --query money
socra cortex module search --query refund

Read each relevant Module before proposing a new one:

socra cortex module get MODULE_NAME

Replace MODULE_NAME with the Module name returned by the search.

Update an existing Module when it already owns the subject. Create a new Module only when the knowledge has no current owner.

Model stable abstractions

Treat a Module like a cohesive programming abstraction. It should own one subject, change for one class of reason, and expose knowledge that other Modules can reuse.

For the refund example, use two Modules:

refunds depends on money because the refund invariants cannot be applied correctly without understanding monetary representation. money does not depend on refunds because monetary representation is useful independently.

Together, these Modules form a small semantic directed acyclic graph (SemDAG): meaning is separated into reusable abstractions, and dependencies assemble those abstractions in comprehension order.

Do not make the graph mirror repository directories, package imports, teams, or documentation folders. A Cortex dependency means required for comprehension.

Write durable knowledge

Good Module content states the current rule and the reason it exists:

Store and transmit monetary values as integer minor units. Pair every value with its ISO 4217 currency code because the currency determines the minor-unit scale. Do not use floating-point values for money. This prevents rounding differences across services and clients.

A refund references one settled charge. The cumulative amount refunded against a charge must not exceed its settled amount. Record each refund independently instead of rewriting the original charge. This preserves an auditable financial history and makes partial refunds composable.

Exclude implementation status, file paths, migration notes, incident history, and instructions that apply only to the current task. The agent must verify changing implementation details from the current system.

Decide when to split

Create separate Modules when either condition is true:

• The knowledge can be understood or reused independently.
• The knowledge has a different owner or changes for a different reason.

Keep knowledge together when splitting it would force every consumer to retrieve both parts to understand either one.

Create the graph

Show the engineer the complete proposed content and dependency list. Continue only after the engineer approves both.

Create the foundation Module:

socra cortex module create --name money --content "Store and transmit monetary values as integer minor units. Pair every value with its ISO 4217 currency code because the currency determines the minor-unit scale. Do not use floating-point values for money. This prevents rounding differences across services and clients."

Create the dependent Module:

socra cortex module create --name refunds --deps money --content "A refund references one settled charge. The cumulative amount refunded against a charge must not exceed its settled amount. Record each refund independently instead of rewriting the original charge. This preserves an auditable financial history and makes partial refunds composable."

If either Module already exists, review its current content and use socra cortex module update to apply only the approved change. The --deps option replaces the complete dependency list; include every direct dependency that must remain.

Verify the assembled expertise

Inspect the map again:

socra cortex map

Confirm that refunds depends on money and that no reverse or unrelated edge exists.

Flash the target Module:

socra cortex flash refunds

Confirm that Cortex returns money before refunds and includes each Module once. The output should contain enough context to explain both monetary representation and refund behavior without requiring the agent to guess either rule.

Apply the expertise to real work

Give the configured coding agent a bounded task:

Flash refunds. Then inspect the current billing implementation and propose the smallest change that supports partial refunds. Apply the flashed decisions, but verify all current implementation details from the repository and tests before changing anything.

The agent should:

1. Flash refunds before making a decision.
2. Read both money and refunds from the assembled context.
3. Inspect the current implementation instead of treating the flash as runtime evidence.
4. Preserve the monetary and refund invariants in its proposed or completed work.

The loop has failed if the agent receives the knowledge but cannot identify when it applies, or if the graph omits knowledge required for the task.

Refine the graph from evidence

Review the agent's work and classify each problem before changing Cortex:

• Missing durable knowledge: Add it to the narrowest Module that owns the subject.
• Wrong abstraction: Split or combine Modules so each has one cohesive responsibility.
• Missing comprehension dependency: Add the direct edge required to understand the target Module.
• Incorrect current-state assumption: Fix the work or verification process. Do not encode changing implementation state as durable knowledge.
• Unrelated execution gap: Create an Issue against the narrowest Module that owns the expected behavior.

Show the engineer every proposed Module change before applying it. After approval, update the Module, flash the target again, and repeat the same task or an equivalent test.

The graph is useful when the agent reliably retrieves the smallest complete body of expertise required for the work. It is not complete merely because it contains many Modules.

Next step

Learn how Modules and dependencies shape the knowledge map, or learn how Issues coordinate work against the same graph.