Skip to content

fix(analyst): let analyst read workspace memory and steer it to workspace skills - #1570

Open
hkaltai wants to merge 8 commits into
mainfrom
fix/analyst-workspace-memory-skills
Open

hkaltai wants to merge 8 commits into
mainfrom
fix/analyst-workspace-memory-skills

Conversation

@hkaltai

@hkaltai hkaltai commented Oct 20, 2026 •

Copy link
Copy Markdown
Contributor

Issue for this PR

Closes #1569

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

In a linked project, analyst could not answer read-only questions like "what are our conventions?": every memory tool was denied, the identity section named a save tool it lacked, and every reply had to go through answer_commit.

  • Analyst may now read, reload and audit workspace memory. Write, delete and extract stay denied; data-explorer is unchanged. A reload syncs like every session's first load (it can drop a local copy of a block the workspace archived) but cannot create or edit memory.
  • The team-memory line names only the memory tools this agent and request keep. The line and tool removal share one rule, LLM.removedTools (agent permission plus tools switched off on the request). Full access keeps today's text; read-only points at the read tool; write-only drops the read-first hint; neither gets no line.
  • The analyst prompt loads a matching skill by the listing's source precedence (workspace and project skills included), answers convention questions in plain text, and still finishes data questions through answer_commit.
  • An empty memory read no longer suggests the write tool, for any agent.
  • Docs: both analyst pages (agent modes and the agents reference) list the new memory, audit-log and skill access.

Small extras beyond the issue: the write-only case is reachable only through user config, and the docs lines.

Before and after

Area Before After
Analyst memory tools All denied (read, reload, audit, write, delete, extract) Read, reload and audit allowed; write, delete and extract still denied
Team-memory line in the identity section Named a save tool analyst could not use Names only the memory tools the agent and request keep (none, read-only, write-only or full)
Empty memory read Suggested the write tool to every agent No write-tool suggestion
Skill choice in the analyst prompt No steer toward workspace or project skills Loads a matching skill by the listing's source precedence, workspace and project skills included
Convention questions ("what are our conventions?") Forced through answer_commit, often with no useful answer Answered in plain text
Data questions Finish through answer_commit Unchanged, still finish through answer_commit
data-explorer agent Memory tools denied Unchanged
Docs Analyst pages did not mention memory or skills Agent modes page and agents reference list the new access, including the local audit log and what a reload changes

Follow-ups (existing behaviour, not changed here)

  • altimate_memory_audit reads only this checkout's local audit log, for every agent. It does not show changes teammates made directly in workspace memory.
  • With tool retrieval turned on (ALTIMATE_TOOL_RETRIEVAL=1, off by default), retrieval can drop a memory tool after the identity line has named it. Before this PR the line named both tools for every agent.

How did you verify your code works?

  • Tests: analyst permission matrix, all four read/write cases of the identity line, a cached outcome rendered per agent, the shared removal rule, and a prompt-loop test tying the identity section to the tools sent to the model.
  • Reverting each fix makes its new test fail.
  • Typecheck clean; affected suites pass.
  • Not done: a live analyst run against a linked workspace (provider returned 402), so the prompt's effect on model choices is checked only at the unit level.

Cost side effects

None. About 110 more tokens in the analyst system prompt and three more tool definitions. No new model calls, queries or resources that grow with user data.

Screenshots / recordings

N/A, no UI change.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

🤖 Generated with Claude Code

Summary by CodeRabbit

  • New Features
    • Analyst agents can read, refresh, and audit workspace memory while delegating memory-saving requests to Builder.
    • Analyst responses can use relevant workspace and project skills to answer questions about team conventions.
    • Workspace guidance now reflects each agent’s available memory capabilities.
    • Memory lookup results provide clearer messaging when no memory is available.
  • Documentation
    • Updated Analyst capability and configuration documentation.
  • Tests
    • Added coverage for memory permissions, skill visibility, prompt behavior, and tool filtering.

…pace skills

In a linked project the read-only analyst agent could not call any memory
tool, yet the workspace identity section told it to save with
`altimate_memory_write` and check `altimate_memory_read`. Its prompt named
only the built-in data skills and required every reply to finish through
`answer_commit`, which suits data values, not a list of conventions.

- analyst may call `altimate_memory_read`, `altimate_memory_refresh` and
  `altimate_memory_audit`; write, delete and extract stay denied, and
  data-explorer is unchanged.
- The team-memory line names only the memory tools the session's agent can
  call: a read-only agent is pointed at the read tool and told that builder
  saves; an agent with neither gets no line.
- The analyst prompt loads a matching skill by source precedence, answers
  questions about team conventions in plain text from skills and memory,
  and keeps `answer_commit` for data questions.

Fixes #1569

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: fd9a97d5-c0f3-4c4f-8154-cb3e9a80984e
📥 Commits

Reviewing files that changed from the base of the PR and between fb215f8 and 212ff7b.

📒 Files selected for processing: 3
  • docs/docs/configure/agents.md
  • docs/docs/data-engineering/agent-modes.md
  • packages/opencode/test/session/prompt.test.ts
+--------------------------------------------------------+
| Code review is a dish best served cold. Like a carrot. |
+--------------------------------------------------------+
  \
   \     /)/)
        ( '')
        /  |
      o(___)

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 3cd5622c-2181-4b43-80d2-aa25dc992f17
📥 Commits

Reviewing files that changed from the base of the PR and between 11bfb29 and fb215f8.

📒 Files selected for processing: 16
  • docs/docs/configure/agents.md
  • docs/docs/data-engineering/agent-modes.md
  • packages/opencode/src/agent/agent.ts
  • packages/opencode/src/altimate/prompts/analyst.txt
  • packages/opencode/src/altimate/workspace/identity.ts
  • packages/opencode/src/memory/tools/memory-read.ts
  • packages/opencode/src/session/llm.ts
  • packages/opencode/src/session/prompt.ts
  • packages/opencode/test/agent/analyst-data-explorer.test.ts
  • packages/opencode/test/altimate/sql-validation-e2e.test.ts
  • packages/opencode/test/altimate/workspace/identity-section.test.ts
  • packages/opencode/test/altimate/workspace/identity.test.ts
  • packages/opencode/test/memory/overlay-merge.test.ts
  • packages/opencode/test/session/llm.test.ts
  • packages/opencode/test/session/prompt.test.ts
  • packages/opencode/test/skill/skill.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

📝 Walkthrough

The Analyst can read, refresh, and audit workspace memory, and its prompt covers workspace skills and non-data replies. Workspace identity guidance now reflects each agent’s available memory tools. Memory saving and deletion remain unavailable to the Analyst.

Changes: Analyst workspace knowledge

Layer / File(s) Summary
Analyst permissions and response rules
packages/opencode/src/agent/agent.ts, packages/opencode/src/altimate/prompts/analyst.txt, docs/docs/configure/agents.md, docs/docs/data-engineering/agent-modes.md, packages/opencode/test/agent/analyst-data-explorer.test.ts, packages/opencode/test/altimate/sql-validation-e2e.test.ts, packages/opencode/test/skill/skill.test.ts
The Analyst gains memory read, refresh, and audit permissions. Its prompt covers workspace skills and plain-text replies to non-data questions; data questions retain answer_commit rules. Documentation and tests cover the permission and prompt changes.
Resolve effective memory-tool access
packages/opencode/src/session/llm.ts, packages/opencode/src/session/prompt.ts, packages/opencode/test/session/llm.test.ts, packages/opencode/test/session/prompt.test.ts
LLM.removedTools centralizes user and agent tool filtering. Session prompt generation uses the resulting memory-tool availability when rendering workspace identity and supplies the filtered tools to the model.
Render capability-specific memory guidance
packages/opencode/src/altimate/workspace/identity.ts, packages/opencode/src/memory/tools/memory-read.ts, packages/opencode/test/altimate/workspace/identity.test.ts, packages/opencode/test/altimate/workspace/identity-section.test.ts, packages/opencode/test/memory/overlay-merge.test.ts
Workspace identity text reflects available memory read/write tools and remains omitted for stale or unconfirmed bindings. Empty memory results no longer direct callers to save memory. Tests cover access combinations and empty results.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant SessionPrompt
  participant LLM
  participant WorkspaceIdentity
  participant Analyst
  participant altimate_memory_read
  SessionPrompt->>LLM: Identify tools disabled by configuration or permissions
  SessionPrompt->>WorkspaceIdentity: Pass available memory read/write permissions
  WorkspaceIdentity-->>SessionPrompt: Return capability-specific memory guidance
  SessionPrompt-->>Analyst: Provide prompt and retained tools
  Analyst->>altimate_memory_read: Read workspace memory
Loading

Suggested reviewers: anandgupta42, sahrizvi

Merge Risk: ⚪ Minimal · up to fb215

The analyst workspace changes are ready to merge after normal checks; no actionable issue was established.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 13 files. (3 skipped:… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the main change: enabling the analyst to read workspace memory and use workspace skills.
Description check Passed The description follows the repository template. It includes the issue, change type, detailed implementation summary, verification results and limitations, cost side effects, screenshots status, and c…
Linked Issues check Passed Issue #1569 has coding requirements. analyst permits altimate_memory_read, altimate_memory_refresh, and altimate_memory_audit, while its rules deny write and delete operations. The agent confi…
Out of Scope Changes check Passed The changes remain within issue #1569. The empty-memory response removes unavailable write-tool guidance. The shared LLM.removedTools helper keeps identity text consistent with request and agent too…
Full details: Description check

Explanation

The description follows the repository template. It includes the issue, change type, detailed implementation summary, verification results and limitations, cost side effects, screenshots status, and completed checklist.

Full details: Linked Issues check

Explanation

Issue #1569 has coding requirements. analyst permits altimate_memory_read, altimate_memory_refresh, and altimate_memory_audit, while its rules deny write and delete operations. The agent configuration keeps data-explorer read-only. The analyst prompt includes workspace and project skill selection, plain-text handling for workspace knowledge, and answer_commit only for data questions. The identity text derives memory guidance from the tools retained after LLM.removedTools. The changed tests cover the permission matrix, identity variants, prompt/tool consistency, skill listing, and finalization behavior. The documentation updates support the same analyst capabilities.

Full details: Out of Scope Changes check

Explanation

The changes remain within issue #1569. The empty-memory response removes unavailable write-tool guidance. The shared LLM.removedTools helper keeps identity text consistent with request and agent tool filtering. The added tests and analyst documentation support the requested behavior. No unrelated product behavior is identified in the reviewed change summary.

Full details: Docstring Coverage

Explanation

Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 13 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

  • Fix all pre-merge checks with AI
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit reads the skill list bright,
And finds the memory blocks in sight.
The Analyst asks, but does not write;
The Builder saves them safe and right.
Workspace notes guide paws along,
Then plain-text answers hop along.

Comment @coderabbitai help to get the list of available commands.

@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

…tool

analyst can now call `altimate_memory_read` but not `altimate_memory_write`.
An empty read told it to "Use altimate_memory_write to save information",
steering a read-only agent toward a call it cannot make. The result now
only says that no blocks were found.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

1 similar comment
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

hkaltai and others added 4 commits October 20, 2026 16:08
…ization rule

The analyst prompt now limits answer_commit to data questions and lets
workspace-knowledge answers finish in plain text; update the pinned
finalization assertion and pin the new exclusion sentence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Share one removal rule (`LLM.removedTools`) between tool resolution and
  the workspace identity section, so a memory tool switched off on the
  request, or not registered, is not named in the prompt.
- A write-only agent gets the save line without the read-first step.
- The analyst prompt checks `altimate_memory_read` only when it has it.
- Update the analyst prompt assertion in sql-validation-e2e to the new
  finalization wording.
- Cover all four read/write combinations and one cached outcome rendered
  for different agents.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
… wiring

- The analyst permission comment now says a reload syncs like the load
  every session runs and can drop a local copy of an archived block,
  rather than calling it read-only.
- The prompt comment scopes the memory line to the tools the agent and
  request keep; tool-free steps withhold every tool the prompt names.
- A prompt-loop test checks that the identity section is given the same
  memory access the tools handed to the model call imply.
- Document analyst's memory and workspace-skill access.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

1 similar comment
@github-actions

Copy link
Copy Markdown

👋 This PR was automatically closed by our quality checks.

Common reasons:

  • New GitHub account with limited contribution history
  • PR description doesn't meet our guidelines
  • Contribution appears to be AI-generated without meaningful review

If you believe this was a mistake, please open an issue explaining your intended contribution and a maintainer will help you.

Match the agent-modes page, and name the prompt-loop memory tests by
what they check.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@hkaltai
hkaltai marked this pull request as ready for review October 20, 2026 14:03
@kilo-code-bot

kilo-code-bot Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (16 files)
  • docs/docs/configure/agents.md
  • docs/docs/data-engineering/agent-modes.md
  • packages/opencode/src/agent/agent.ts
  • packages/opencode/src/altimate/prompts/analyst.txt
  • packages/opencode/src/altimate/workspace/identity.ts
  • packages/opencode/src/memory/tools/memory-read.ts
  • packages/opencode/src/session/llm.ts
  • packages/opencode/src/session/prompt.ts
  • packages/opencode/test/agent/analyst-data-explorer.test.ts
  • packages/opencode/test/altimate/sql-validation-e2e.test.ts
  • packages/opencode/test/altimate/workspace/identity-section.test.ts
  • packages/opencode/test/altimate/workspace/identity.test.ts
  • packages/opencode/test/memory/overlay-merge.test.ts
  • packages/opencode/test/session/llm.test.ts
  • packages/opencode/test/session/prompt.test.ts
  • packages/opencode/test/skill/skill.test.ts

Reviewed by gemini-4-argon · Input: 519.4K · Output: 1.7K · Cached: 1.1M

Review guidance: REVIEW.md from base branch main (truncated)

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

3 issues found across 16 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/opencode/test/session/prompt.test.ts">

<violation number="1" location="packages/opencode/test/session/prompt.test.ts:635">
P3: This test never checks the rendered memory text, because `systemSection` is mocked to return "". It only checks the flags passed in. Rename it to describe what it asserts, or add a no-access turn (both tools denied) so the loop covers the case the PR description lists.</violation>
</file>

<file name="packages/opencode/src/agent/agent.ts">

<violation number="1" location="packages/opencode/src/agent/agent.ts:343">
P2: `altimate_memory_audit` reads only this checkout's local `.log`, so it cannot show teammate changes made directly in workspace memory. Add a workspace-aware audit source before exposing it as workspace auditing.</violation>
</file>

<file name="packages/opencode/src/session/prompt.ts">

<violation number="1" location="packages/opencode/src/session/prompt.ts:1923">
P2: `tools` is only the pre-stream catalog: retrieval can still remove either memory tool, so this line can advertise an action the model cannot call. Derive these flags from the final tool set or ensure the named memory tools survive retrieval.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/opencode/src/agent/agent.ts
Comment thread packages/opencode/src/session/prompt.ts
Comment thread docs/docs/configure/agents.md Outdated
Comment thread packages/opencode/test/session/prompt.test.ts Outdated
Comment thread docs/docs/data-engineering/agent-modes.md Outdated
@dev-punia-altimate

Copy link
Copy Markdown
Contributor

🤖 Code Review — OpenCodeReview (Gemini) — No Issues Found

No comments generated. Looks good to me.

Add an analyst turn with no memory tools to the prompt-loop test and name
the test for what it asserts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

analyst agent cannot read workspace memory and is not steered to workspace skills

2 participants