Give the system a directory: ask who knows, then ask them

A memory system that only answers from its own store is a filing cabinet,
not a partner. The transactive rule the project is named for — not knowing
is fine when you know who does — needed a holder registry, a directory
query, and a referral that never leaks the text it may not read.

- schema v5 adds `holders` (person/agent/service, declared topics, contact).
  A holder with memories exists whether or not anybody registered them; the
  registry adds reachability, it does not grant existence.
- `who_knows` ranks holders by their own memories and is deliberately NOT
  filtered by visibility: "she knows" is the answer. The answer is filtered.
- `ask` searches the asker's visible scope first (hop 0), then walks the
  directory with a visited set and a hop budget. Three terminal states:
  answered, referred, no_holder_knows. Nobody knowing is a result, not an error.
- Confidence is ordinal, not calibrated: relative strength, coverage, and
  declared topics. Every hit carries the raw numbers and the basis lines that
  produced the score, so a ranking can be argued with.
- Faces: HTTP (/api/holders, /api/who_knows, /api/ask), CLI (holders,
  holder-set, holder-rm, who-knows, ask), MCP (who_knows, ask, list_holders).

Four bugs found by running the thing, not by reading it:
- FTS5 refuses bm25() inside MAX(); the aggregate uses FTS5's own `rank` column.
- A CJK question is longer than the sentence that answers it, so the whole-run
  phrase matched nothing. The query now ORs adjacent bigram phrases; adjacency
  is kept, equal length is not. Latin path untouched, baseline unaffected.
- The hop budget counted the asker as a hop, so max_hops=1 asked nobody.
- A second, stricter readability test in _answered() disagreed with the SQL
  visibility clause and hid a memory the asker was allowed to read. The SQL
  clause is the only authority now.

A method named `list` shadowed the builtin inside its own class and made
mypy reject the return annotation; renamed rather than cast around it.

Proof: 155 pytest, 12 Go tests, ruff and mypy clean on touched files, pyright
ledger unchanged at 62, and scripts/mcp_write_smoke.sh drives two principals
on one SQLite file — the husband asks through MCP, gets `referred` with his
wife's contact channel, and her private sentence appears nowhere in the reply.
This commit is contained in:
ZacharyZhang-NY committed 2026-10-07 17:20:45 -04:00
1 parent 9fe13fffb3
commit dfc6cd4c28
19 files changed
+1403 -19

No files matched your search

@@ -0,0 +1,102 @@
package mcpserver
import (
"context"
"errors"
"github.com/ZacharyZhang-NY/ely-eye/ely-eye-mcp/internal/domain"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type WhoKnowsInput struct {
Query string `json:"query" jsonschema:"what the asker wants to know, in the asker's own words"`
AsHolder string `json:"as_holder,omitempty" jsonschema:"who is asking; decides which memories may be shown"`
Limit int `json:"limit,omitempty" jsonschema:"how many candidates to return, default 8"`
}
type AskInput struct {
Question string `json:"question" jsonschema:"the question to answer from memory"`
AsHolder string `json:"as_holder,omitempty" jsonschema:"who is asking; their own memory is checked first"`
MaxHops int `json:"max_hops,omitempty" jsonschema:"how many holders besides the asker may be asked, default 3"`
IncludeText bool `json:"include_text,omitempty" jsonschema:"show the memory text when the asker may already read it"`
}
// registerDirectoryTools exposes the transactive surface: who knows, and ask-and-get-referred.
func (s *Server) registerDirectoryTools(server *mcp.Server) {
mcp.AddTool(server, &mcp.Tool{
Title: "Who knows",
Name: "who_knows",
Description: "Rank the holders whose memories answer a query, with the evidence and how to reach them. The directory counts memories the asker cannot read; that is the point. no_holder_knows is a result, not a failure.",
}, s.whoKnows)
mcp.AddTool(server, &mcp.Tool{
Title: "Ask and get referred",
Name: "ask",
Description: "Ask the asker's own memory, then the directory. answered means somebody's memory matched; referred means the best holder's memory is private, so the answer is the pointer and contact, never the text.",
}, s.askMemory)
mcp.AddTool(server, &mcp.Tool{
Title: "List holders",
Name: "list_holders",
Description: "List registered holders: the people, agents, and services a referral can walk to.",
}, s.listHolders)
}
type whoKnowsOutput struct {
Report domain.WhoKnowsReport `json:"report" jsonschema:"the ranked candidates and their evidence"`
}
type askOutput struct {
Answer domain.ReferralAnswer `json:"answer" jsonschema:"who answered, who was asked, and what may be shown"`
}
type holdersOutput struct {
Holders []domain.Holder `json:"holders" jsonschema:"the registered holders"`
}
func (s *Server) whoKnows(ctx context.Context, _ *mcp.CallToolRequest, in WhoKnowsInput) (*mcp.CallToolResult, whoKnowsOutput, error) {
if in.Query == "" {
return nil, whoKnowsOutput{}, errors.New("query is required")
}
var report domain.WhoKnowsReport
body := map[string]any{"query": in.Query}
if in.AsHolder != "" {
body["as_holder"] = in.AsHolder
}
if in.Limit > 0 {
body["limit"] = in.Limit
}
if err := s.api.Post(ctx, "/api/who_knows", body, &report); err != nil {
return nil, whoKnowsOutput{}, err
}
return nil, whoKnowsOutput{Report: report}, nil
}
func (s *Server) askMemory(ctx context.Context, _ *mcp.CallToolRequest, in AskInput) (*mcp.CallToolResult, askOutput, error) {
if in.Question == "" {
return nil, askOutput{}, errors.New("question is required")
}
var answer domain.ReferralAnswer
body := map[string]any{"question": in.Question}
if in.AsHolder != "" {
body["as_holder"] = in.AsHolder
}
if in.MaxHops > 0 {
body["max_hops"] = in.MaxHops
}
if in.IncludeText {
body["include_text"] = true
}
if err := s.api.Post(ctx, "/api/ask", body, &answer); err != nil {
return nil, askOutput{}, err
}
return nil, askOutput{Answer: answer}, nil
}
func (s *Server) listHolders(ctx context.Context, _ *mcp.CallToolRequest, _ struct{}) (*mcp.CallToolResult, holdersOutput, error) {
var holders []domain.Holder
if err := s.api.Get(ctx, "/api/holders", &holders); err != nil {
return nil, holdersOutput{}, err
}
return nil, holdersOutput{Holders: holders}, nil
}
@@ -0,0 +1,133 @@
package mcpserver
import (
"context"
"encoding/json"
"io"
"net/http"
"net/http/httptest"
"strings"
"testing"
"github.com/ZacharyZhang-NY/ely-eye/ely-eye-mcp/internal/apiclient"
)
func directoryServer(t *testing.T, body string, seen *[]string) *httptest.Server {
t.Helper()
return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
payload, _ := io.ReadAll(r.Body)
*seen = append(*seen, r.Method+" "+r.URL.Path+" "+string(payload))
w.WriteHeader(http.StatusOK)
_, _ = w.Write([]byte(body))
}))
}
func TestWhoKnowsNamesTheHolderAndKeepsTheEvidence(t *testing.T) {
var seen []string
server := directoryServer(t, `{"query":"钥匙","as_holder":"husband","status":"found","hits":[{
"holder_id":"wife","name":"小美","confidence":0.91,"matched":2,"top_score":0.02,
"basis":["wife holds 2 matching memories the asker may not read"],"contact":{"channel":"signal"}}]}`, &seen)
defer server.Close()
_, out, err := (&Server{api: apiclient.New(server.URL)}).whoKnows(
context.Background(), nil, WhoKnowsInput{Query: "钥匙", AsHolder: "husband"})
if err != nil {
t.Fatalf("who_knows failed: %v", err)
}
if out.Report.Status != "found" || len(out.Report.Hits) != 1 {
t.Fatalf("report = %+v, want one found candidate", out.Report)
}
hit := out.Report.Hits[0]
if hit.HolderID != "wife" || hit.Confidence != 0.91 || hit.Contact["channel"] != "signal" {
t.Errorf("hit = %+v, want the holder, her confidence, and how to reach her", hit)
}
if len(seen) != 1 || !strings.Contains(seen[0], "POST /api/who_knows") || !strings.Contains(seen[0], `"query":"钥匙"`) {
t.Fatalf("requests = %v, want one POST carrying the query", seen)
}
}
func TestWhoKnowsRefusesAnEmptyQueryBeforeTheNetwork(t *testing.T) {
var seen []string
server := directoryServer(t, `{}`, &seen)
defer server.Close()
if _, _, err := (&Server{api: apiclient.New(server.URL)}).whoKnows(context.Background(), nil, WhoKnowsInput{}); err == nil {
t.Fatal("an empty query must not reach the directory")
}
if len(seen) != 0 {
t.Errorf("requests = %v, want none", seen)
}
}
func TestAskReturnsThePointerAndNotThePrivateText(t *testing.T) {
var seen []string
server := directoryServer(t, `{"question":"钥匙在哪里","as_holder":"husband","status":"referred",
"answered_by":"wife","asked":["husband","wife"],"hops":1,"atom_ids":[],"basis":["wife holds 1 matching memories the asker may not read"]}`, &seen)
defer server.Close()
_, out, err := (&Server{api: apiclient.New(server.URL)}).askMemory(
context.Background(), nil, AskInput{Question: "钥匙在哪里", AsHolder: "husband", MaxHops: 2})
if err != nil {
t.Fatalf("ask failed: %v", err)
}
if out.Answer.Status != "referred" || out.Answer.Answer != "" {
t.Errorf("answer = %+v, want a referral with no text", out.Answer)
}
if out.Answer.AnsweredBy != "wife" || out.Answer.Hops != 1 {
t.Errorf("answer = %+v, want wife at hop 1", out.Answer)
}
if !strings.Contains(seen[0], `"max_hops":2`) || !strings.Contains(seen[0], `"as_holder":"husband"`) {
t.Errorf("request = %s, want the hop budget and the asker", seen[0])
}
}
func TestAskWithoutAnAskerOmitsTheIdentity(t *testing.T) {
var seen []string
server := directoryServer(t, `{"question":"garage code","status":"no_holder_knows","asked":[],"hops":0}`, &seen)
defer server.Close()
if _, _, err := (&Server{api: apiclient.New(server.URL)}).askMemory(context.Background(), nil, AskInput{Question: "garage code"}); err != nil {
t.Fatalf("ask failed: %v", err)
}
var body map[string]any
parts := strings.SplitN(seen[0], " ", 3)
if err := json.Unmarshal([]byte(parts[2]), &body); err != nil {
t.Fatalf("request body is not JSON: %s", seen[0])
}
if _, present := body["as_holder"]; present {
t.Errorf("body = %v, want as_holder omitted so the server applies its own default", body)
}
if _, present := body["max_hops"]; present {
t.Errorf("body = %v, want max_hops omitted; a Go zero is not a hop budget", body)
}
}
func TestAskRefusesAnEmptyQuestion(t *testing.T) {
var seen []string
server := directoryServer(t, `{}`, &seen)
defer server.Close()
if _, _, err := (&Server{api: apiclient.New(server.URL)}).askMemory(context.Background(), nil, AskInput{}); err == nil {
t.Fatal("an empty question must not be asked")
}
if len(seen) != 0 {
t.Errorf("requests = %v, want none", seen)
}
}
func TestListHoldersReadsTheRegistry(t *testing.T) {
var seen []string
server := directoryServer(t, `[{"holder_id":"wife","name":"小美","kind":"person","knows_about":["家里的钥匙"],"contact":{"channel":"signal"},"created_at":"2026-05-01T00:00:00+00:00","updated_at":"2026-05-01T00:00:00+00:00"}]`, &seen)
defer server.Close()
_, out, err := (&Server{api: apiclient.New(server.URL)}).listHolders(context.Background(), nil, struct{}{})
if err != nil {
t.Fatalf("list_holders failed: %v", err)
}
if len(out.Holders) != 1 || out.Holders[0].KnowsAbout[0] != "家里的钥匙" {
t.Fatalf("holders = %+v, want the declared topics", out.Holders)
}
if len(seen) != 1 || !strings.HasPrefix(seen[0], "GET /api/holders") {
t.Errorf("requests = %v, want one GET", seen)
}
}
+1
View File
@@ -37,6 +37,7 @@ func Run(ctx context.Context, cfg config.Config, version string) error {
})
server.registerTools(mcpServer)
server.registerWriteTools(mcpServer)
server.registerDirectoryTools(mcpServer)
server.registerMountTools(mcpServer)
server.registerResources(mcpServer)
if err := mcpServer.Run(ctx, &mcp.StdioTransport{}); err != nil {