Find the task. Run the steps.

Teach your harness how every AI session should start and end.

A new AI chat starts with no project history. A Brutha Primer is the small start pack that gives your assistant its role, active decisions, key tasks, and current project context before it starts work.

You build the Primer once in three steps. First, add start and save rules to your agent harness. Second, ask the agent to create a default Character. Third, ask it to seed the workspace with lasting project memories.

A harness is the file that gives standing instructions to your AI assistant. Use the instruction file that matches your tool.

A Character is the stable role, standards, and work habits for an agent. The default Primer Character loads with that workspace at the start of each session.

1. Create or open the instruction file for your tool. Use its global instruction file when the same rule should apply to all projects.
2. Paste the harness block below and replace payments-api with your workspace name.
3. Open a fresh agent chat and paste the Character prompt below. The agent calls character_save with is_default_primer set to true.
4. Paste the seed prompt. The agent scans the repo, runs code_index_repo, and saves checked facts with memory_save.
5. Start one more fresh chat. The harness tells the agent to call primer before reading or editing code.
6. At the end of work, the harness tells the agent to save only durable decisions, fixes, and handoffs. Chat filler is not saved.

# Brutha memory workflow

Workspace: `payments-api`

Before you read or edit code:
1. Call Brutha `primer` for this workspace.
2. If no default Character loads, call `memory_recall`, list the workspace Characters, and activate the default role.
3. Summarize the active goal, key decisions, and open risks.

During work:
- Keep persona rules in the Character and changing project facts in memories.
- Check Brutha code impact before a broad refactor.
- Never save secrets or chat filler.

Before you end the session:
- Save durable decisions, fixed bugs, lessons, and handoff state to Brutha.
- Include the returned `Brutha-Memory: <uuid>` receipt in any agent handoff.

Create a default primer Character for the `payments-api` workspace named `payments-architect`. Set `is_default_primer` to true so Brutha loads it at the start of every session. Include our TypeScript rules, database safety rules, test expectations, and review checklist. Keep changing project facts out of the Character. Tell me what you saved.

Scan this repository, index its code graph, and save the core architecture decisions, build commands, test commands, deployment rules, and current risks to Brutha in the `payments-api` workspace. Save only facts you can verify from the repo. Use clear memory types and tell me which memories will appear in future Primer packs.

Load the Brutha Primer for this workspace. Summarize the active Character, current goal, key decisions, open handoffs, and any stale facts I should review before we begin.

Keep client and project context apart on one computer.

When one assistant works on several projects, facts from one project can leak into another chat. Brutha workspaces keep memories and Characters scoped to names such as product-plan, research-notes, and personal.

A Character is the stable role and work style for an agent. Each workspace can have its own default Character, plus extra roles that you activate for a special task.

1. Choose one stable workspace name for each repo. Add that name to the repo harness file.
2. Add the start rule below. It tells the agent to call primer with the right workspace before work.
3. Ask the agent to create the default Character with the first prompt. It calls character_save and sets is_default_primer to true.
4. Repeat in the next repo with its workspace name and Character prompt.
5. To add a second role in one workspace, use the role prompt below. The agent creates it without making it the default.
6. To switch roles, ask the agent to list Characters, activate the role you name, and release it when the task ends.
7. Test isolation by asking each repo agent to recall its workspace. Confirm that facts from the other project do not appear.

# Brutha workspace

Use Brutha workspace `payments-api` for every memory and Character call in this repo. Run `primer` for this workspace before touching code. Save durable project facts back to this workspace only.

Create a Character named `payments-architect` in the `payments-api` workspace. Make it the default Primer Character. Give it our payment safety, TypeScript, database, test, and review rules. Keep release status and other changing facts in memories, not in the Character.

Create a Character named `mobile-lead` in the `mobile-app` workspace. Make it the default Primer Character. Give it our mobile access, offline, test, and release rules. Keep changing app state in memories.

In the `payments-api` workspace, create a non-default Character named `security-reviewer` with our security review checklist. List the workspace Characters, activate `security-reviewer` for this task, and release it after the review. Report each Brutha tool you used.

Keep stable agent behavior out of changing project history.

An agent becomes unreliable when old release facts live in its persona or when core behavior lives in memories that can age out. Brutha keeps these jobs separate so your agent stays steady while project facts change.

A Character defines who the assistant is. It holds role, tone, work rules, standing checks, workflow steps, and a preferred model hint. A memory records what happened in the project, such as a decision, lesson, feedback, pattern, or handoff.

1. Add the separation rule below to your harness so every agent follows it.
2. Paste the audit prompt into your AI assistant. It uses character_list and character_update to clean each Character.
3. The agent saves any useful project facts it removes with memory_save and the right memory type.
4. The agent searches for persona rules that were saved as memories. It writes one checked correction and links it to old items with memory_link using supersedes.
5. If several items conflict, the agent uses memory_reconcile and reports the final rule.
6. Review the agent's list before it changes shared Characters or shared memories.

• Character content: stable role, standards, safety rules, review checklist, and expected workflow.
• Memory content: product decisions, research findings, current project state, fixes, results, and handoffs.
• Never place dates, current ticket state, or release status in a Character.
• Never rely on a normal memory to hold the agent's permanent persona rules.

# Persona and memory boundary

Characters hold only stable role and behavior rules. Memories hold only project facts that can change over time. Before saving either one, classify the content. Never move dated project state into a Character. Never use a normal memory as the permanent source of persona rules.

Audit this workspace for mixed persona and project content. List all Characters and remove dated facts, task status, bug notes, and release state from them. Save useful removed facts as typed Brutha memories. Then search memories for role, tone, coding style, and standing workflow rules. Propose corrections, link replacements to old memories as superseding them, and reconcile conflicts. Show me the plan before changing shared items.

Keep active work fast while old history stays available.

Long projects can collect thousands of facts. If every fact enters every session, the agent wastes tokens and misses current work. Brutha uses memory tiers to keep active context near the top without deleting history.

Hot memories are new or recently recalled. Warm memories have not been used for a set time and rank lower in start packs. Cold memories stay out of automatic Primer snippets but remain searchable.

Decay changes recall rank, not the saved record. Recalling or expanding a warm memory makes it hot again. Strong use and supporting facts help core decisions stay active.

1. Ask your agent to inspect the current memory_decay schedule and explain it in plain words.
2. Review warm_days, cold_days, interval_days, and enabled. A common starting point is 30 days for warm and 90 days for cold.
3. Ask the agent to show sample memories from each tier before changing the schedule.
4. Approve the tuning prompt only after the samples look right. The agent calls memory_decay with the new settings.
5. Ask the agent to search and expand one cold memory. This proves that cold history is still safe.
6. Use timeline synthesis when you need the full history of a long-running subject.

Inspect Brutha's memory decay settings for this workspace. Explain warm_days, cold_days, interval_days, and whether scheduled decay is enabled. Show a few safe examples from the hot, warm, and cold tiers. Do not change settings yet.

Set Brutha memory decay to move unused memories to warm after 30 days and cold after 90 days. Run the sweep every 7 days and enable the schedule. Run one sweep now, then search for an old cold memory and prove that it can still be expanded. Report every setting you changed.

Use Brutha to synthesize a timeline of our release process. Include older cold memories when they explain how the process changed.

Help software engineers check code impact before broad edits.

This optional guide is for software engineers and architects. An AI assistant can change one function and miss the routes, callers, and tests tied to it. Brutha gives the assistant a structural code map and impact checks before it edits.

Your harness should make this automatic. The agent uses code_map for task context, code_index_repo for a saved repo index, code_impact for blast radius, and code_trace or code_neighbors for deeper links.

1. Add the impact rule below to your repo harness.
2. Ask the agent to index a clean checkout once. It calls code_index_repo and reports the indexed commit.
3. Before a broad refactor, give the impact prompt. The agent runs code_impact before editing.
4. Review the listed callers, routes, tests, and saved code memories.
5. After the edit, ask the agent to rerun impact checks and the named tests.
6. Ask it to link durable design decisions to key symbols with code_memory_link so later agents can load them with code_memory_context.

# Brutha code checks

Before a broad edit, use Brutha to map the task area and check blast radius. Read direct neighbors and call paths when risk is unclear. Name the affected routes and tests before editing. After the change, rerun impact checks and the affected tests. Link lasting design decisions to the code symbols they govern.

Before you edit the authentication service, use Brutha to map this area and check the blast radius of the sign-in flow. List callers, routes, tests, and linked memories. Trace any unclear dependency path. Propose the smallest safe edit and wait for approval.

Pass checked work through planning, writing, review, and operations stages.

Each agent in a loop starts a fresh session. Without a saved handoff, the next agent repeats work, misses proof, or retries the same failure forever. Brutha gives each stage one verified record and one receipt to load.

A Brutha-Memory receipt is the UUID returned when the agent saves a handoff. The next agent expands that exact ID before work, so it starts from checked state rather than a summary copied from chat.

1. Add the loop rules below to the parent harness or each subagent definition.
2. At the end of a stage, the agent calls memory_save with type handoff. It includes result, proof, blocker, next task, source role, target role, project, and strike count.
3. The agent puts the returned Brutha-Memory receipt in its handoff message.
4. The next stage calls memory_expand on that receipt before it acts. It can search the target tag or synthesize the project timeline for more context.
5. After another attempt, the agent saves a new handoff and links it to the prior record with memory_link using supersedes.
6. Set a strike limit in the harness. When the same failure reaches that limit, stop the loop and escalate with evidence.

# Brutha agent handoffs

At the start of your stage:
- Expand the Brutha-Memory receipt from the prior stage.
- Confirm the project, target role, proof, open task, and strike count.

At the end of your stage:
- Save one typed `handoff` memory with verified results, commands run, test output, blocker, and next action.
- Tag it with `from:<role>`, `to:<role>`, and `strike:<n>`.
- Link it as superseding the prior handoff.
- Return `Brutha-Memory: <uuid>` in your final message.

Stop and escalate after 2 strikes on the same failure.

Act as the validator. Load Brutha-Memory `<uuid>` before doing any work. Confirm the prior agent's claimed changes and test proof. Run the missing checks. Save a new verified handoff for the reviewer, link it to the prior handoff, and return the new Brutha-Memory receipt. Stop and escalate if this is strike 2 for the same failure.

Keep useful context for product, research, writing, support, legal, sales, and software work.

Brutha is not limited to software work. Any professional who uses an AI assistant can keep decisions, source notes, approved facts, and work habits ready for the next session.

Use separate workspaces when projects need different sources or rules. Use Characters when each kind of work needs a steady role, tone, or review list.

1. Create one workspace for the project or client.
2. Ask your AI assistant to save a checked decision, source note, or work rule.
3. Start a new chat and ask the assistant to run primer for that workspace.
4. Confirm that it recalls the right facts without mixing in another project.

• Product, strategy, and operations teams save product choices, customer research, meeting notes, and roadmap changes.
• Researchers, analysts, and writers use memory_synthesize for long studies, import_docs for markdown notes, and character_activate for a steady style.
• Support, legal, and go-to-market teams keep approved facts and review rules ready while personal drafts stay private.
• Software engineers and architects use code_map and code_impact to check a repository before a broad edit.

Use Brutha workspace `customer-launch`. Recall approved product choices, research findings, support guidance, legal review notes, and launch messages. Keep private drafts out of shared results. Tell me which sources you used before you begin.

Move from one AI assistant to another without losing checked context.

Tool changes often reset the conversation and force you to explain the repo again. When each tool uses the same workspace and start rules, Brutha gives the next agent the same Character, decisions, and handoff state.

1. Run the Solo installer again and select every AI tool you plan to use.
2. Put the same workspace name and Primer rule in each tool's harness file.
3. Before leaving the first tool, use the handoff prompt below. The agent saves verified state and returns a receipt.
4. Open the next tool and paste the resume prompt with that receipt.
5. The next agent runs primer, expands the receipt, and states the next task before editing.

./brutha-mcp install
./brutha-mcp status

Save a Brutha handoff for this workspace. Include the current goal, files changed, decisions, tests run, failures, and exact next step. Return the Brutha-Memory receipt.

Run the Brutha Primer for this workspace, then expand Brutha-Memory `<uuid>`. Confirm the current goal, proof, and next step. Do not edit until you tell me whether the handoff matches the repo.

Bring Obsidian, Logseq, or markdown docs into one workspace.

Your AI assistant cannot use years of notes if they live outside its context. The import command adds markdown sections to a Brutha workspace while your source files stay in place.

1. Back up the vault before the first import.
2. Run import-docs with the vault path and target workspace.
3. Open your AI assistant and ask it to search for one known note.
4. Run the same import after note changes. Brutha refreshes the collection instead of stacking copies.

./brutha-mcp import-docs ~/Notes/Vault --workspace payments-api

Search Brutha in the `payments-api` workspace for our retry policy note. Expand the best match, name its source collection, and tell me if it conflicts with a newer code decision.

Let a smaller, lower-cost model prepare broad recall for your main assistant.

Broad memory questions can send too much text to a large model. The local Memory Broker asks a smaller, lower-cost model to sort recall first, then gives your main assistant a short result.

1. Keep broker.py in your local Brutha tools folder.
2. Set `provider/fast-model` or another smaller model and the Brutha workspace in the broker settings.
3. Run the broker with a broad question and inspect its short result.
4. Add the harness rule below so your AI assistant uses the broker for broad history questions and direct Brutha recall for exact IDs.
5. Check memory_token_savings in your agent after a week to compare reuse.

export BRUTHA_BROKER_MODEL='provider/fast-model'
python broker.py --workspace payments-api "What changed in the release flow?"

Use the local Brutha Memory Broker for broad project-history questions. Use direct Brutha memory expansion when a handoff gives an exact UUID. Keep the final context focused on the current task.

Find stale facts and settle conflicts before they mislead your agent.

Old facts can conflict with current code and send an agent down the wrong path. A regular Brutha review finds stale records, keeps a clear timeline, and preserves the checked replacement.

1. Add a monthly memory review to your project harness or maintenance checklist.
2. Give the review prompt to your agent. It checks staleness hints and searches for conflicts.
3. Approve each proposed correction. The agent uses memory_reconcile or saves a replacement linked with supersedes.
4. Ask the agent to run an end-session review after large milestones and save only durable results.
5. Use the memory tier guide to move unused history out of automatic Primer packs.

Review this Brutha workspace for stale facts and conflicts. Compare high-risk memories with the current repo. Propose corrections before writing them. Reconcile conflicts, link replacements as superseding old facts, and finish with a timeline of what changed.

Give local scripts and non-MCP agents access through HTTP.

Some agents do not support MCP. Brutha can expose a local HTTP service so your own harness can use the same workspace memory without moving data to another system.

HTTP is a common way for programs to send requests to each other. Keep this service bound to your own computer unless you add strong network access controls.

1. Start the local HTTP service on the loopback address shown below.
2. Point your custom harness at that address and choose its Brutha workspace.
3. Test recall and one safe write from the harness.
4. Stop the test service. Install the daemon only when you want Brutha to start with the computer.
5. Run status and doctor after daemon setup.

./brutha-mcp http --bind 127.0.0.1:8765
./brutha-mcp status

./brutha-mcp daemon install
./brutha-mcp status
./brutha-mcp doctor

Protect local memory before software or computer changes.

Your Primer and project history are valuable local data. A backup before updates or computer moves protects that work if a file is lost or damaged.

1. Close connected coding tools so they release the local database.
2. Copy the SQLite file to an encrypted backup folder.
3. Run the update command, then restart each coding tool.
4. Run status and doctor. Open an agent and ask it to load the workspace Primer.
5. If recall fails, rerun install for that coding tool and test again.

mkdir -p ~/Backups/brutha
cp ~/.brutha/brutha.db ~/Backups/brutha/brutha-$(date +%Y%m%d).db
./brutha-mcp update
./brutha-mcp status
./brutha-mcp doctor