Memory Tool V1
Memory Tool V1
Objective
Define a standalone memory API that stores reusable solved-case information and returns ranked reusable records to other tools.
This tool is not a planner, not a governance engine, and not a research runtime.
Its purpose is to:
- store reusable records
- retrieve similar prior records
- expand linked artifacts and evidence
- rank likely reuse candidates for a new task
Role In The System
The intended tool boundaries are:
research-toolGenerates and evaluates candidate solutionsmemory-toolStores and retrieves prior reusable knowledgeplanner-toolBuilds scoped DAGs from selected solutionsgovernance-toolApplies approval, validation, and execution controls
The memory tool is a support layer for the others. It is never the source of final authority.
Boundary With Evidence Search
The memory tool stores curated internal reusable records.
The evidence-search tool retrieves external papers, benchmarks, and references.
Only evidence that materially contributed to a useful solution should be curated into memory later as linked references. Memory should not become a dump of all external search results.
Non-Goals
V1 should not become:
- a giant universal graph
- a chat transcript archive
- hidden runtime state
- an autonomous reasoning engine
- a canonical workflow tracker
V1 is a retrieval system for curated reusable records.
Admission Policy
Memory should be default-deny for long-term storage.
Only admit records that are likely to be reusable:
- solved problems
- high-value rejected alternatives with clear lessons
- reusable code artifacts
- reusable evaluation harnesses
- reusable planner fragments
- curated linked evidence that materially informed a useful solution
Do not automatically admit:
- all intermediate candidate variants
- all exploratory failures
- raw chat transcripts
- every external source retrieved during evidence search
- giant run-state blobs
If retrieval quality degrades because of volume, curation policy should tighten before storage volume expands.
Core Use Cases
Use Case 1: Similar Problem Search
Input:
- new problem statement
- constraints
- repo or code context
Output:
- ranked prior
problem_recordentries - linked
solution_recordentries
Use Case 2: Reusable Solution Search
Input:
- current technical problem
- desired artifact type
- constraints
Output:
- ranked reusable
solution_recordentries - linked code, prompts, schemas, or harnesses
Use Case 3: Artifact Expansion
Input:
- record id
Output:
- related artifacts
- related evaluations
- provenance links
Use Case 4: Reuse Ranking
Input:
- current problem packet
- retrieved candidate records
Output:
- ranked reusable candidates
- explanation of ranking factors
API Surface
V1 should stay small.
store_record
Purpose:
- persist one typed memory record
Input:
record_typerecord
Output:
record_idstatusversion
get_record
Purpose:
- fetch one stored record by id
Input:
record_id
Output:
record_typerecordlinked_record_ids
search_records
Purpose:
- retrieve candidate records using lexical, metadata, and optional semantic matching
Input:
queryrecord_typesfilterstop_k
Output:
matchessearch_metadata
link_records
Purpose:
- create lightweight reusable relationships between records
Input:
from_idto_idrelationweight
Output:
link_idstatus
get_related_records
Purpose:
- expand a record into linked reusable context
Input:
record_idrelation_filtersdepth
Output:
recordsedges
rank_reusable_candidates
Purpose:
- re-rank retrieved memory candidates for the current problem
Input:
current_problem_packetcandidate_record_idsorcandidate_recordsranking_policy
Output:
ranked_candidatesranking_explanations
Record Types
problem_record
Purpose:
- normalized representation of a previously solved or investigated problem
Minimum fields:
problem_idtitlesummaryconstraintscontext_tagsfingerprintstatuscreated_at
solution_record
Purpose:
- reusable solution pattern or winning candidate
Minimum fields:
solution_idproblem_idsummaryapproach_typeartifact_refsevaluation_refsreusability_tagsadaptation_notesstatus
artifact_record
Purpose:
- reusable concrete object such as code, prompt, schema, DAG fragment, or evaluation harness
Minimum fields:
artifact_idartifact_typepath_or_urisymbol_refslanguageinputsoutputs
evaluation_record
Purpose:
- empirical evidence for whether a solution worked
Minimum fields:
evaluation_idsolution_idmethodmetricsenvironmentresultnotes
plan_fragment_record
Purpose:
- reusable planning pattern, subgraph, or execution slice
Minimum fields:
plan_fragment_idsummarynode_refsdependency_patternartifact_refsconstraints
policy_record
Purpose:
- reusable governance or approval pattern
Minimum fields:
policy_idsummarypolicy_typeapplicability_tagsartifact_refs
Relationship Model
Use lightweight edges, not a monolithic graph document.
Supported initial relations:
solvesusesvalidated_byderived_fromsimilar_tosupersedesadapted_into
Each edge should include:
from_idto_idrelationweightcreated_at
Storage Model
V1 should use a hybrid local-first model:
- canonical typed record store
- lightweight relation index
- searchable text index
- optional semantic index behind an abstraction
Recommended first implementation:
SQLitefor canonical records and edge tablesFTSfor text search- optional embeddings later
Avoid one giant JSON graph file.
Retrieval Pipeline
Retrieval should be staged.
Stage 1: Recall
Find candidate prior records using:
- lexical search
- tags
- constraints
- repo or language filters
Stage 2: Filter
Drop candidates that do not fit:
- language/runtime constraints
- architecture constraints
- artifact type requirements
- validation quality requirements
Stage 3: Expand
Load linked:
- solutions
- artifacts
- evaluations
- plan fragments
Stage 4: Re-Rank
Apply explicit reuse scoring for the current task.
Stage 5: Return
Return ranked candidates plus provenance and linked artifacts.
Ranking Model
Do not rank only by semantic similarity.
V1 ranking dimensions should be:
problem_similarityconstraint_matchartifact_reusabilityprior_success_rateevidence_strengthadaptation_costrecency
Conceptual scoring shape:
reuse_score = similarity + constraint_match + evidence_strength + success_rate + recency - adaptation_cost
The exact weights should be configurable.
Ranking Output Contract
Each ranked candidate should return:
record_idrecord_typereuse_scorescore_breakdownmatched_constraintsmissing_constraintstop_artifact_refstop_evaluation_refsadaptation_notes
Curation Rules
Only store memory that is likely to be reusable.
Store:
- solved problems
- winning or high-value rejected solutions
- reusable code artifacts
- reusable evaluation harnesses
- reusable planner fragments
Do not store:
- all intermediate thoughts
- every failed draft
- raw chat logs by default
- giant nested runtime blobs
Integration With Research Tool
The research-tool should call memory in two places:
Before Search
Use:
search_recordsrank_reusable_candidates
Purpose:
- see if a similar problem was already solved
- import reusable artifacts before generating new candidates
After A Good Result
Use:
store_recordlink_records
Purpose:
- preserve good solutions, evaluations, and artifacts for future reuse
Integration With Planner Tool
The planner-tool should retrieve:
- reusable plan fragments
- reusable dependency patterns
- reusable artifact bundles
It should not treat memory output as canonical DAG state.
Integration With Governance Tool
The governance-tool may retrieve:
- precedent solutions
- prior evaluation evidence
- reusable policy objects
It should still make fresh approval decisions in the current context.
Failure Modes To Avoid
- memory becoming hidden authority
- unbounded graph growth
- low-signal records dominating search results
- embeddings replacing explicit filtering
- reused code without linked evaluation evidence
- stale solutions outranking validated recent ones
V1 Implementation Sequence
- define record schemas
- define API request and response packets
- implement typed storage
- implement lexical search and metadata filters
- implement relation expansion
- implement explicit reuse ranking
- integrate with
research-tool
V1 Exit Criteria
V1 is successful when:
- a new problem can retrieve similar prior solved cases
- retrieved candidates can be ranked for reuse
- linked artifacts and evaluations can be expanded deterministically
- the research tool can store new winning solutions for future reuse
- the system remains small and queryable