Spark Memory Layer

Spark is a shared memory and documentation layer for you and the rest of your team. It contains all the information you need to learn from everything important in software development. Query Spark for recommendations on your current task, and do so multiple times during a session.

Using Spark

Spark exposes a cli tool called spark that you can use to query it. The commands are detailed below.

When working with Spark, it is very important that you never share any secrets, api keys or other sensitive information.

Spark is entirely private to your team, so be specific about what you share. Specific learnings on how internal APIs work are extremely valuable, as are design patterns and best practices for how the current repository is built. References to internal concepts are really important. Use the repository as a reference for how to use the APIs.

Use Spark Memory to get access to, and supply information on, all things you would search for in the documentation and internal knowledge base. Includes asking for best practices for:

• how tests should be set up
• how to use internal resources and apis
• how infrastructure should be set up
• how to use the current repository
• patterns to use for given domains
• and much more!

Commands

query

The main entry point for Spark. Send a query to Spark for content in the memory and documentation stores. The query uses both keyword and semantic search, but is intended for a single concept per query. If you need varied information, make multiple queries.

As part of the query you can supply tags to help Spark narrow down the results. The key tags to use are:

Type	Purpose	Example names
language	Programming language	python, typescript, rust
library	Software library or framework	fastmcp, express, react
api	External API you are interacting with	stripe, github, openai
task_type	The aim of the task	implementation, bug_fix, migration, refactor
repository	The current repository you are working on	acme-auth

language, library and api should also be supplied with version when available to you. The repository tag is important to ensure you are looking at the right information.

The cli signature is:

spark query <query> --xml-tag <tag>

where <query> is the query string and <tag> is a tag in the form <tag type="language" name="python" version="3.12" />, where version is optional and type taken from the table above.

The response will contain a list of results, if any results were found. It will contain documents and memories that match the query in xml format.

The end of the response contains a session-id (id-N), which is important to keep track of when you want to contribute to the memory.

Examples

Example — querying about streaming responses:

spark query "how to handle streaming responses in FastMCP" \
  --xml-tag '<tag type="language" name="python" version="3.12" />' \
  --xml-tag '<tag type="library" name="fastmcp" version="2.14" />' \
  --xml-tag '<tag type="task_type" name="implementation" />'

Example — multiple questions require separate queries:

# Question 1: how does this library handle auth?
spark query "how does the Acme SDK handle authentication" \
  --xml-tag '<tag type="language" name="typescript" />' \
  --xml-tag '<tag type="library" name="acme-sdk" version="3.2" />'

# Question 2: what about retry logic? (separate query, different topic)
spark query "what is the retry and backoff strategy in the Acme SDK" \
  --xml-tag '<tag type="language" name="typescript" />' \
  --xml-tag '<tag type="library" name="acme-sdk" version="3.2" />'

share

Regardless of if you got relevant information from Spark for your query or not, contribute insights related to answering that query once you have reached an answer.

If you got relevant information from Spark, only supply new relevant insights. If no data was found in Spark yet, supply all relevant insights to the query. Ensure to do this for all relevant queries posed.

spark share <session-id> \
  --title "<short description>" \
  --content "<solution details, supports markdown>" \
  --task-index <index> \
  --xml-tag '<tag type="..." name="..." />'
  --sources <doc-id-1>,<doc-id-2>,<insight-id-1>

--title and --content are required. --task-index is required (set to 'new' if no task is relevant to the solution you are sharing). --sources accepts comma-separated insight/document IDs from Spark. --xml-tag is optional and will override any tags from the original query, otherwise your original tags will be used.

Examples

spark share id-5 \
  --title "FastMCP streaming workaround" \
  --content "Use async generators with yield to avoid buffering issues in FastMCP streaming responses." \
  --task-index task-0 \
  --xml-tag '<tag type="language" name="python" version="3.12" />' \
  --xml-tag '<tag type="library" name="fastmcp" version="2.14" />' \
  --xml-tag '<tag type="task_type" name="bug_fix" />'

For new tasks, where no matching task was found in the query to the solution you are sharing,

spark share id-5 \
  --title "FastMCP streaming workaround" \
  --content "Use async generators with yield to avoid buffering issues in FastMCP streaming responses." \
  --task-index "new" \
  --xml-tag '<tag type="language" name="python" version="3.12" />' \
  --xml-tag '<tag type="library" name="fastmcp" version="2.14" />' \
  --xml-tag '<tag type="task_type" name="bug_fix" />'

share-task

If, during your work, you do extensive research on a task, and especially if you get corrected by your human colleague, you can contribute the new information to Spark, even if you did not performed a query initially for this.

Use the share-task command to contribute this new information to Spark:

spark share-task "<query>" \
  --title "<title of insight to share>" \
  --content "<content of insight to share>" \
  --xml-tag '<tag type="..." name="..." />'

xml-tag is optional and are described in the query command. The query here is what you think that you should have searched for to get this information in the first place. The --title and --content flags are required. --title should be a short description of the insight, --content should be a detailed description of the insight.

Example

spark share-task "how to handle streaming responses in FastMCP" \
  --title "FastMCP streaming workaround" \
  --content "Use async generators with yield to avoid buffering issues in FastMCP streaming responses." \
  --xml-tag '<tag type="language" name="python" version="3.12" />' \
  --xml-tag '<tag type="library" name="fastmcp" version="2.14" />'

feedback

Feedback is critical for the memory layer to improve. Use the feedback command to provide feedback on the quality of the recommendations you got from Spark. Doing this helps Spark evolve and both positive and negative feedback are important.

spark feedback <session-id> --feedback '<feedback idx="TYPE-IDX" relevant="true|false" correct="true|false">comment</feedback>'

The idx is taken from the recommendations. Set relevant to true if the result was a good match for the query, and correct to true if the content was accurate.

Example:

spark feedback id-5 --feedback '<feedback idx="doc-1" relevant="true" correct="true">The document contained exactly what I needed.</feedback>'