Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ DETERMINISTIC_PKGS := \
./internal/memory/embed \
./internal/memory/graph \
./internal/memory/importdraft \
./internal/memory/judge \
./internal/memory/internal/topk \
./internal/memory/model \
./internal/memory/search \
Expand Down
22 changes: 22 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -574,6 +574,28 @@ export MNEMON_EMBED_API_KEY=pa-...
mnemon embed --status
```

**Decision-model judge** (optional, opt-in per command):

| Environment Variable | Default | Description |
|---|---|---|
| `MNEMON_JUDGE_MODEL` | *(empty = disabled)* | System One model name, e.g. `clef` or `clef-flash` (local Ollama), `karpo-decision` (self-hosted Karpo Decision), `jev-latest` (TypeSafe) |
| `MNEMON_JUDGE_ENDPOINT` | `http://localhost:11434` | Base URL of a System One server (`POST {endpoint}/v1/systemone`) |
| `MNEMON_JUDGE_API_KEY` | *(none)* | Bearer token for cloud endpoints such as `https://api.typesafe.ai` or `https://api.subq.ai` |
| `MNEMON_JUDGE_TIMEOUT` | `15s` | Total time budget for one judgment, across all of its requests (Go duration) |

`mnemon recall --judge` asks the judge whether each ranked result is about the
same subject as the query, adds a `relevance` probability to every result, and
drops results below `--judge-min` (default `0.5`). `mnemon remember --judge`
classifies each semantic candidate as `duplicate`,
`supersedes`, `contradicts`, `related`, or `unrelated` and reports it as
`judgment` on that candidate; it never creates edges. Without `--judge`, output
is unchanged, and if the judge is missing or fails, mnemon prints a one-line
warning to stderr and returns normal output.

> **Privacy:** the judge sends the query and the text of the judged memories to
> `MNEMON_JUDGE_ENDPOINT`. A cloud endpoint therefore receives that text; keep
> the default local Ollama endpoint if memories must not leave the machine.

## Development

```bash
Expand Down
1 change: 1 addition & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ service; its model is under "Network service" below. Key security considerations
- **SQLite database** — contains all stored insights; protected by filesystem permissions (`0644`).
- **Hook scripts** — shell scripts executed by the LLM CLI at lifecycle events; written with `0755` permissions.
- **Embedding provider connection** — optional requests send insight or query text to the configured Ollama or OpenAI-compatible server. The default local Ollama endpoint does not use TLS. If `MNEMON_EMBED_ENDPOINT` points outside a trusted local network, use HTTPS to protect content and any `MNEMON_EMBED_API_KEY` bearer token in transit.
- **Decision-model judge connection** — only when `--judge` is passed and `MNEMON_JUDGE_MODEL` is set, `recall` and `remember` send the query and the text of the judged memories to `MNEMON_JUDGE_ENDPOINT`. A cloud endpoint therefore receives that text. The default local Ollama endpoint does not use TLS; use HTTPS for any other endpoint to protect content and the `MNEMON_JUDGE_API_KEY` bearer token.

### Network service (memory cloud instances)

Expand Down
1 change: 1 addition & 0 deletions cmd/memory/brief.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ type briefResult struct {
Score *float64 `json:"score,omitempty"`
Confidence string `json:"confidence,omitempty"`
Superseded bool `json:"superseded,omitempty"`
Relevance *float64 `json:"relevance,omitempty"`
}

type briefResponse struct {
Expand Down
140 changes: 140 additions & 0 deletions cmd/memory/judge.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
package memory

import (
"context"
"fmt"
"os"
"strings"

"github.com/mnemon-dev/mnemon/internal/memory/graph"
"github.com/mnemon-dev/mnemon/internal/memory/judge"
"github.com/mnemon-dev/mnemon/internal/memory/search"
)

// judgeContentChars caps how much of one memory is sent to the judge, keeping
// a full request well under the 64 KiB body limit of a local server.
const judgeContentChars = 1200

// relationOptions are the choices offered when classifying how a new memory
// relates to an existing semantic candidate.
var relationOptions = map[string]string{
"duplicate": "the new memory says the same thing as the existing one",
"supersedes": "the new memory updates or replaces the existing one",
"contradicts": "the new memory conflicts with the existing one without clearly replacing it",
"related": "same subject, different facts",
"unrelated": "different subjects",
}

// judgment is the judge's classification of one semantic candidate.
type judgment struct {
Relation string `json:"relation"`
Probability float64 `json:"probability"`
}

// judgedCandidate is a semantic candidate with an optional judgment. A
// candidate the judge did not classify serializes exactly as before.
type judgedCandidate struct {
graph.SemanticCandidate
Judgment *judgment `json:"judgment,omitempty"`
}

// warnJudge prints a one-line advisory; the judge never fails a command.
func warnJudge(format string, args ...any) {
msg := strings.Join(strings.Fields(fmt.Sprintf(format, args...)), " ")
fmt.Fprintf(os.Stderr, "warning: %s\n", msg)
}

// clipRunes truncates s to at most n runes.
func clipRunes(s string, n int) string {
runes := []rune(s)
if len(runes) <= n {
return s
}
return string(runes[:n])
}

// judgeRecall scores every result against the query and drops those below
// --judge-min. It fails open: when the judge is missing or errors, resp is
// left untouched.
func judgeRecall(query string, resp *search.RecallResponse) {
jc := judge.NewClient()
if jc == nil {
warnJudge("--judge ignored: MNEMON_JUDGE_MODEL is not set")
return
}
if len(resp.Results) == 0 {
return
}
memories := make(map[string]string, len(resp.Results))
questions := make([]judge.Question, len(resp.Results))
for i, r := range resp.Results {
name := fmt.Sprintf("m%d", i)
memories[name] = clipRunes(r.Insight.Content, judgeContentChars)
questions[i] = judge.Question{
Name: name,
Instructions: fmt.Sprintf(
"Is memory `%s` about the same subject as `query`, so it could help answer it?", name),
}
}
state := map[string]any{"query": query, "memories": memories}
scores, err := jc.Noul(context.Background(), state, questions)
if err != nil {
warnJudge("judge unavailable, returning unjudged results: %v", err)
return
}
kept := make([]search.RecallResult, 0, len(resp.Results))
for i, r := range resp.Results {
relevance := roundScore(scores[questions[i].Name])
if relevance < recJudgeMin {
continue
}
r.Relevance = &relevance
kept = append(kept, r)
}
resp.Results = kept
}

// judgeCandidates classifies each semantic candidate, auto-linked ones
// included: a near-identical candidate is the likeliest duplicate or
// superseded memory.
// It returns false, leaving the caller's output unchanged, when there is
// nothing to judge or the judge is missing or errors.
func judgeCandidates(content string, candidates []graph.SemanticCandidate) ([]judgedCandidate, bool) {
jc := judge.NewClient()
if jc == nil {
warnJudge("--judge ignored: MNEMON_JUDGE_MODEL is not set")
return nil, false
}
existing := make(map[string]string)
var questions []judge.ChoiceQuestion
for i, c := range candidates {
name := fmt.Sprintf("c%d", i)
existing[name] = clipRunes(c.Content, judgeContentChars)
questions = append(questions, judge.ChoiceQuestion{
Name: name,
Instructions: fmt.Sprintf(
"How does `new_memory` relate to existing memory `%s`?", name),
Options: relationOptions,
})
}
if len(questions) == 0 {
return nil, false
}
state := map[string]any{
"new_memory": clipRunes(content, judgeContentChars),
"existing_memories": existing,
}
answers, err := jc.Choice(context.Background(), state, questions)
if err != nil {
warnJudge("judge unavailable, leaving candidates unjudged: %v", err)
return nil, false
}
out := make([]judgedCandidate, len(candidates))
for i, c := range candidates {
out[i] = judgedCandidate{SemanticCandidate: c}
if a, ok := answers[fmt.Sprintf("c%d", i)]; ok {
out[i].Judgment = &judgment{Relation: a.Choice, Probability: roundScore(a.Probability)}
}
}
return out, true
}
Loading
Loading