Give memories a working tier, a long-term tier, and a record of what disagrees

A memory used to have one state: present. A session could not be reloaded
without searching, nothing separated what a person said today from what the
store ingested a year ago, and two statements that disagree about a number
were both handed to the reader as if the store believed both.

Schema v10. Atoms gain session_id, importance, recall_count, last_recalled_at
and archived_at; two tables arrive beside them — consolidations (one watermark
per holder+scenario lane) and conflicts (a pair, the term they disagree on,
both values, and whether anyone has settled it). v_atoms_current now also
hides archived rows, and apply() drops the view before rebuilding it because
CREATE VIEW IF NOT EXISTS would keep the old body and ignore the archive.

Working memory is a read, not a store: `working <holder> <session>` returns
what that session recorded, in order, with no search involved. Consolidation
rolls a lane's new memories into one standing summary and moves the watermark
to the newest memory actually rolled up — not to the clock of the pass, which
made a second pass count the same memories twice. The archive rule is stated
in the command that runs it (recorded before N days, never returned by a
search, importance at or under a floor) rather than hidden in a decay formula
nobody measured; --dry-run names the victims first.

A conflict is recorded when a new memory repeats a label with a different
number in the same holder's same scenario. Retrieval drops the older side
while the conflict is open and both sides answer again once it is settled:
settling is not superseding, and a word-only disagreement is left alone
because a reworded sentence would fire on every paraphrase. Numbers are keyed
to both the memory's subject and the nearest preceding label, measured: the
two thermostat sentences share only their subject, so a nearest-word-only rule
found nothing.

Search now counts the memories it handed back, which is the only use estimate
the store has, and the archive rule reads it. The dense index applies the same
currency rules as the view, so an archived memory cannot stay findable through
one leg while the other hides it.

Two reads over HTTP (working, conflicts) and two tools over MCP
(working_set, memory_conflicts); curation stays with the operator because an
agent should not decide what its own past is worth. remember and supersede
carry a session id; importance does not cross MCP, because recall_count is
observed and importance is stated.

Gates: 366 passed; ruff clean; mypy 24 errors in 9 files, the recorded 9cb46c1
baseline, net 0; pyright 0 on the touched files; go build/vet/test and gofmt
clean; mcp_write_smoke PASS.
This commit is contained in:
ZacharyZhang-NY committed 2026-10-09 07:13:11 -04:00
1 parent 4c6af87fe0
commit dc9cfb5a30
30 files changed
+1814 -229

No files matched your search

+2 -1
View File
@@ -33,12 +33,13 @@ func Run(ctx context.Context, cfg config.Config, version string) error {
Title: "Ely-Eye Context Cartridge MCP",
Version: version,
}, &mcp.ServerOptions{
Instructions: "Use Ely-Eye tools to retrieve local cartridge context, evidence atoms, proof suites, and compiled evidence packs. Read tools mirror local Ely-Eye state without writing. remember, supersede_memory and forget_memory mutate memory through the Ely-Eye API, which must be running (`ely-eye serve`); the server, not the caller, decides who owns a memory. mount_cartridge and switch_cartridge decide what a search may see: mount a cartridge to ask only that cartridge, and unmount everything to ask the whole library.",
Instructions: "Use Ely-Eye tools to retrieve local cartridge context, evidence atoms, proof suites, and compiled evidence packs. Read tools mirror local Ely-Eye state without writing. remember, supersede_memory and forget_memory mutate memory through the Ely-Eye API, which must be running (`ely-eye serve`); the server, not the caller, decides who owns a memory. mount_cartridge and switch_cartridge decide what a search may see: mount a cartridge to ask only that cartridge, and unmount everything to ask the whole library. working_set reloads what one session already recorded, in order, without searching; memory_conflicts reports what the store has not reconciled, and settling one is the operator's act, not a tool's.",
})
server.registerTools(mcpServer)
server.registerWriteTools(mcpServer)
server.registerDirectoryTools(mcpServer)
server.registerMountTools(mcpServer)
server.registerTierTools(mcpServer)
server.registerResources(mcpServer)
if err := mcpServer.Run(ctx, &mcp.StdioTransport{}); err != nil {
if errors.Is(err, io.EOF) || strings.HasSuffix(err.Error(), "EOF") {
@@ -0,0 +1,57 @@
package mcpserver
import (
"context"
"github.com/ZacharyZhang-NY/ely-eye/ely-eye-mcp/internal/domain"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type WorkingSetInput struct {
Holder string `json:"holder" jsonschema:"whose session this is"`
Session string `json:"session" jsonschema:"the session whose memories to load, in the order they were recorded"`
}
type ConflictsInput struct {
Holder string `json:"holder,omitempty" jsonschema:"limit the list to one holder; empty lists every disagreement in the store"`
}
type WorkingSetOutput struct {
Atoms []domain.Memory `json:"atoms"`
}
type ConflictsOutput struct {
Conflicts []domain.ConflictRecord `json:"conflicts"`
}
// registerTierTools exposes the two reads a session needs: what it already
// recorded, and what the store has not reconciled yet. Curation stays on the
// operator's CLI, because an agent should not decide what its own past is worth.
func (s *Server) registerTierTools(server *mcp.Server) {
mcp.AddTool(server, &mcp.Tool{
Name: "working_set",
Title: "Load a session's working memory",
Description: "Return everything one holder recorded in one session, oldest first, with no ranking involved. Use it to resume a conversation rather than to search it.",
}, s.workingSetTool)
mcp.AddTool(server, &mcp.Tool{
Name: "memory_conflicts",
Title: "List unsettled memory conflicts",
Description: "Return disagreements the store noticed between two memories and nobody has settled. While one stands, a search answers with the newer side and hides the older one.",
}, s.conflictsTool)
}
func (s *Server) workingSetTool(ctx context.Context, _ *mcp.CallToolRequest, input WorkingSetInput) (*mcp.CallToolResult, WorkingSetOutput, error) {
atoms, err := s.api.WorkingSet(ctx, input.Holder, input.Session)
if err != nil {
return nil, WorkingSetOutput{}, err
}
return nil, WorkingSetOutput{Atoms: atoms}, nil
}
func (s *Server) conflictsTool(ctx context.Context, _ *mcp.CallToolRequest, input ConflictsInput) (*mcp.CallToolResult, ConflictsOutput, error) {
records, err := s.api.Conflicts(ctx, input.Holder)
if err != nil {
return nil, ConflictsOutput{}, err
}
return nil, ConflictsOutput{Conflicts: records}, nil
}
@@ -0,0 +1,109 @@
package mcpserver
import (
"context"
"net/http"
"net/http/httptest"
"testing"
"github.com/ZacharyZhang-NY/ely-eye/ely-eye-mcp/internal/apiclient"
)
// askingServer records the path and query string of every request so a test can
// prove the tool asked for the session it was given, not a guess built from it.
func askingServer(t *testing.T, body string, seen *[]string) *httptest.Server {
t.Helper()
return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
*seen = append(*seen, r.URL.Path+"?"+r.URL.RawQuery)
w.Header().Set("Content-Type", "application/json")
_, _ = w.Write([]byte(body))
}))
}
func TestWorkingSetAsksForTheSessionAndKeepsWhatTheStoreSaw(t *testing.T) {
var seen []string
server := askingServer(t, `[
{"atom_id":"mem-1:text","holder_id":"妻子","session_id":"cooking-2026-10","text":"钥匙在玄关抽屉","recall_count":3,"importance":null,"last_recalled_at":null},
{"atom_id":"mem-2:text","holder_id":"妻子","session_id":"cooking-2026-10","text":"恒温器调到 24 度","recall_count":0,"importance":0.8,"last_recalled_at":"2026-10-09T04:00:00+00:00"}
]`, &seen)
defer server.Close()
s := &Server{api: apiclient.New(server.URL)}
_, out, err := s.workingSetTool(context.Background(), nil, WorkingSetInput{Holder: "妻子", Session: "cooking-2026-10"})
if err != nil {
t.Fatalf("working_set failed: %v", err)
}
if len(seen) != 1 || seen[0] != "/api/memory/working?holder=%E5%A6%BB%E5%AD%90&session=cooking-2026-10" {
t.Fatalf("the tool asked %v, want the holder and session encoded on the query", seen)
}
if len(out.Atoms) != 2 || out.Atoms[0].Text != "钥匙在玄关抽屉" || out.Atoms[1].Text != "恒温器调到 24 度" {
t.Fatalf("working set = %+v, want the store's order kept", out.Atoms)
}
if out.Atoms[0].SessionID != "cooking-2026-10" || out.Atoms[0].RecallCount != 3 {
t.Errorf("a working set that drops the session id or the recall count is half-blind, got %+v", out.Atoms[0])
}
if out.Atoms[0].Importance != nil {
t.Errorf("a null importance became %v, want it left unset", *out.Atoms[0].Importance)
}
if out.Atoms[1].Importance == nil || *out.Atoms[1].Importance != 0.8 {
t.Errorf("importance = %v, want the stated 0.8", out.Atoms[1].Importance)
}
}
func TestWorkingSetRefusesARequestWithoutASession(t *testing.T) {
var seen []string
server := askingServer(t, `[]`, &seen)
defer server.Close()
s := &Server{api: apiclient.New(server.URL)}
if _, _, err := s.workingSetTool(context.Background(), nil, WorkingSetInput{Holder: "wife"}); err == nil {
t.Fatal("a working set without a session was accepted, but a session is what makes it a working set")
}
if len(seen) != 0 {
t.Errorf("the tool reached for the network with %v before refusing, want the request refused locally", seen)
}
}
func TestMemoryConflictsNamesBothSidesOfTheDisagreement(t *testing.T) {
var seen []string
server := askingServer(t, `[
{"conflict_id":7,"older_atom_id":"mem-1:text","newer_atom_id":"mem-2:text","holder_id":"wife","scenario":"home","terms":["恒温"],"older_value":"22","newer_value":"24","detected_at":"2026-10-09T04:00:00+00:00","resolved_at":null}
]`, &seen)
defer server.Close()
s := &Server{api: apiclient.New(server.URL)}
_, out, err := s.conflictsTool(context.Background(), nil, ConflictsInput{Holder: "wife"})
if err != nil {
t.Fatalf("memory_conflicts failed: %v", err)
}
if len(seen) != 1 || seen[0] != "/api/memory/conflicts?holder=wife" {
t.Fatalf("the tool asked %v, want the holder on the query", seen)
}
if len(out.Conflicts) != 1 {
t.Fatalf("conflicts = %+v, want the one unsettled pair", out.Conflicts)
}
record := out.Conflicts[0]
if record.OlderAtomID == "" || record.NewerAtomID == "" || record.OlderValue != "22" || record.NewerValue != "24" {
t.Errorf("conflict = %+v, want both sides and both values so the caller can pick one", record)
}
if len(record.Terms) != 1 || record.Terms[0] != "恒温" {
t.Errorf("terms = %v, want the term the two memories disagree about", record.Terms)
}
if record.ResolvedAt != "" {
t.Errorf("resolved_at = %q, want an unsettled conflict reading as unresolved", record.ResolvedAt)
}
}
func TestMemoryConflictsWithoutAHolderAsksForEveryHolder(t *testing.T) {
var seen []string
server := askingServer(t, `[]`, &seen)
defer server.Close()
s := &Server{api: apiclient.New(server.URL)}
if _, _, err := s.conflictsTool(context.Background(), nil, ConflictsInput{}); err != nil {
t.Fatalf("memory_conflicts failed: %v", err)
}
if len(seen) != 1 || seen[0] != "/api/memory/conflicts?" {
t.Fatalf("the tool asked %v, want no holder filter so the whole store is listed", seen)
}
}
@@ -11,6 +11,7 @@ import (
type RememberInput struct {
Text string `json:"text" jsonschema:"the statement to remember, kept verbatim"`
Scenario string `json:"scenario,omitempty" jsonschema:"optional context label such as home or work"`
Session string `json:"session_id,omitempty" jsonschema:"the conversation this belongs to; working_set reloads a session in order"`
EventTime string `json:"event_time,omitempty" jsonschema:"when it was true, ISO 8601 with offset, e.g. 2026-05-01T12:00:00+08:00"`
EventTimePrecision string `json:"event_time_precision,omitempty" jsonschema:"instant, minute, hour, day, month, or year; required with event_time"`
RetentionUntil string `json:"retention_until,omitempty" jsonschema:"ISO 8601 with offset; the memory stops being retrievable after this"`
@@ -20,6 +21,7 @@ type SupersedeInput struct {
AtomID string `json:"atom_id" jsonschema:"exact Evidence Atom id being replaced"`
Text string `json:"text" jsonschema:"the newer statement, kept verbatim"`
Scenario string `json:"scenario,omitempty" jsonschema:"optional context label such as home or work"`
Session string `json:"session_id,omitempty" jsonschema:"the conversation this belongs to; working_set reloads a session in order"`
EventTime string `json:"event_time,omitempty" jsonschema:"when the new statement became true, ISO 8601 with offset"`
EventTimePrecision string `json:"event_time_precision,omitempty" jsonschema:"instant, minute, hour, day, month, or year; required with event_time"`
}