@krimto-labs/krimto 0.2.36 → 0.2.37

package/README.md

@@ -9,8 +9,8 @@ place and reads the right slice of it — Alice's preferences override the team'
 conventions override the org's standards, and every fact carries a paper trail (author, source,
 timestamp, reviewer).
 
-> **Where we are:** **v0.2.36** is the current release — the v0.2.17 wizard redesign is now
-> shipped end-to-end, plus nineteen patch releases of correctness fixes and agent-friendly
+> **Where we are:** **v0.2.37** is the current release — the v0.2.17 wizard redesign is now
+> shipped end-to-end, plus twenty patch releases of correctness fixes and agent-friendly
 > surface. The v0.2.16 architecture (markdown-in-git storage, `user → team → org` hierarchy,
 > hybrid retrieval, server-enforced access, two-way git sync, MCP over stdio + HTTP, the Docker
 > image, the web UI) is unchanged. What you get on top of v0.2.16:
@@ -41,7 +41,7 @@ timestamp, reviewer).
 >   first, waits for `:8080` to accept TCP, then writes editor configs. Cursor's file
 >   watcher never fires into an unbound port (the v0.2.27/28 ECONNREFUSED fix).
 >
-> **The agent story (v0.2.34 → v0.2.36).**
+> **The agent story (v0.2.34 → v0.2.37).**
 > - **Phase B agent flags** — `editors --add cursor`, `service --always`, `search --keyword`,
 >   `reset --yes`, `remote --set <url>`, `folder --to <path>`. Every command that used to
 >   open an interactive prompt now has a flag form.
@@ -58,6 +58,10 @@ timestamp, reviewer).
 >   service into team mode itself (no copy-paste recipe, no lock conflict), saves invite keys
 >   to a 0600 backup file, and validates the git remote URL at the prompt. `krimto notes` now
 >   works from any terminal (identity falls back to `git config user.email`).
+> - **Write-time duplicate backstop (v0.2.37)** — `krimto_write` flags a near-duplicate fact in
+>   the same scope (a `related` list + a hint to `krimto_supersede`), so memory doesn't silently
+>   accumulate two facts about the same thing even when the agent skips `krimto_recall`. Backed
+>   by a new retrieval-quality eval that asserts recall returns the right fact first.
 >
 > See [ROADMAP.md](ROADMAP.md), [CHANGELOG.md](CHANGELOG.md), and the proposal-vs-reality
 > diff in [docs/krimto-v0.2.17-maria-journey.html §09](docs/krimto-v0.2.17-maria-journey.html)
@@ -503,7 +507,7 @@ Cline — is table stakes today, so Krimto ships it but doesn't lead with it.
 ## Roadmap
 
 `v0.2` (teams, v0.2.5) → `v0.2.18` (v0.2.17 wizard redesign — published as one SemVer-clean
-release) → `v0.2.36` (correctness + agent-friendly polish — current) → `v0.3` (OAuth + PR approval
+release) → `v0.2.37` (correctness + agent-friendly polish — current) → `v0.3` (OAuth + PR approval
 flow) → `v1.0` (Krimto Cloud). See [ROADMAP.md](ROADMAP.md) for the per-release breakdown.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krimto-labs/krimto",
-  "version": "0.2.36",
+  "version": "0.2.37",
   "description": "Open-source team memory layer for AI agents — markdown files in git, user/team/org hierarchy, cross-vendor MCP server.",
   "license": "Apache-2.0",
   "type": "module",

package/src/server/index.ts

@@ -54,7 +54,7 @@ import { type Requester } from "../access/scope";
 
 export type RequesterResolver = (extra: { authInfo?: AuthInfo }) => Requester;
 
-export const KRIMTO_VERSION = "0.2.36";
+export const KRIMTO_VERSION = "0.2.37";
 
 export function resolveDataDir(): string {
   return process.env.KRIMTO_DATA ?? path.join(homedir(), ".krimto");
@@ -121,7 +121,9 @@ export function buildServer(ctx: ToolContext, resolveRequester?: RequesterResolv
         "durable fact, or when correcting a mistake you should not repeat. For the user's personal " +
         "scope use `user/me` (the server resolves it to their identity) — do not guess an email. The " +
         "write is rejected (with the list of scopes you may write to) if you target a scope you couldn't " +
-        "read back. Call krimto_recall first to avoid duplicates.",
+        "read back. Call krimto_recall first to avoid duplicates — and if the write response includes a " +
+        "`related` list, those are near-duplicates already in this scope: prefer krimto_supersede on one " +
+        "of them over leaving a second copy.",
       inputSchema: {
         scope: z
           .string()

package/src/server/tools.ts

@@ -9,7 +9,7 @@ import { isValidScope, type Requester } from "../access/scope";
 import { canRead, canWrite, isOrgAdmin, type Membership } from "../access/membership";
 import { FactIndex } from "../index/factIndex";
 import { Serializer } from "../index/serialize";
-import { rankCandidates } from "../retrieval/pipeline";
+import { lexicalSimilarity, rankCandidates } from "../retrieval/pipeline";
 import { type CommitBatcher } from "../storage/batcher";
 import { type ActivityLog } from "./activity";
 import { KrimtoError } from "./errors";
@@ -47,6 +47,12 @@ export interface WriteInput {
   source?: string;
   supersedes?: string[];
 }
+export interface RelatedFact {
+  id: string;
+  title: string;
+  /** Hybrid-retrieval score of the existing fact against the new one's title+body. */
+  score: number;
+}
 export interface WriteResult {
   id: string;
   scope: string;
@@ -56,6 +62,12 @@ export interface WriteResult {
   /** Human-readable hint for the agent to relay back. Teaches "this is just a file you can open." */
   hint: string;
   commit_sha: string | null;
+  /**
+   * Existing facts in the same scope that closely resemble the one just written. Surfaced so a
+   * weak agent that skipped krimto_recall still gets a chance to krimto_supersede instead of
+   * duplicating. Omitted when nothing similar was found.
+   */
+  related?: RelatedFact[];
 }
 
 export interface RecallInput {
@@ -148,6 +160,39 @@ function writableScopesFor(ctx: ToolContext): string[] {
   return scopes;
 }
 
+/**
+ * Token-cosine bar above which an existing fact is "the same thing, said again" rather than
+ * merely sharing a word. Tuned from the smoke-6 cases: a near-duplicate (pizza vs pizza+sushi)
+ * scores ~0.8 and a same-topic update (pizza vs tacos) ~0.7, while two facts that only share a
+ * generic qualifier (favorite FOOD vs favorite COLOR) score ~0.38. 0.5 sits cleanly between.
+ */
+const DUPLICATE_SIMILARITY_THRESHOLD = 0.5;
+
+/**
+ * Existing facts in `scope` that closely resemble `${title} ${body}` — the server-side backstop
+ * for the "call krimto_recall first" rule. FTS narrows the candidate set; token cosine then
+ * filters out facts that merely share a generic word. Excludes anything the new write already
+ * supersedes (no point nagging about a fact it's replacing). Top 3, most-similar first.
+ */
+async function findRelatedFacts(
+  ctx: ToolContext,
+  scope: string,
+  title: string,
+  body: string,
+  supersedes: string[] | undefined,
+  now: Date,
+): Promise<RelatedFact[]> {
+  const text = `${title} ${body}`;
+  const candidates = await ctx.index.searchCandidates(text, { readableScopes: [scope], now });
+  const excluded = new Set(supersedes ?? []);
+  return candidates
+    .filter((c) => !excluded.has(c.id))
+    .map((c) => ({ id: c.id, title: c.title, score: lexicalSimilarity(text, `${c.title} ${c.body}`) }))
+    .filter((r) => r.score >= DUPLICATE_SIMILARITY_THRESHOLD)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 3);
+}
+
 /** Create a new fact. Author comes from the requester identity; scope is required. */
 export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<WriteResult> {
   // "user/me"/"user/self" (and bare "me"/"self") mean the caller's own personal scope. An agent
@@ -179,6 +224,14 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
     });
   }
   return ctx.writeQueue.run(async () => {
+    // Run the near-duplicate check BEFORE the new fact is indexed, so it can't match itself.
+    // Best-effort: a failure here must never block a write — the hint is observational.
+    let related: RelatedFact[] = [];
+    try {
+      related = await findRelatedFacts(ctx, scope, input.title, input.body, input.supersedes, clock(ctx));
+    } catch {
+      /* dedup hint is advisory — never let it break the write path */
+    }
     const fact = createFact({
       scope,
       title: input.title,
@@ -224,6 +277,12 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
         `git auto-commits every 30s, run \`npx @krimto-labs/krimto --help\` for the full CLI surface, ` +
         `or \`npx @krimto-labs/krimto storage\` for the storage model.)`;
     }
+    if (related.length > 0) {
+      const list = related.map((r) => `"${r.title}" (${r.id})`).join(", ");
+      hint +=
+        `\n⚠ Similar existing fact${related.length > 1 ? "s" : ""} in this scope: ${list}. ` +
+        `If this updates ${related.length > 1 ? "one of them" : "it"}, call krimto_supersede instead of leaving a duplicate.`;
+    }
     return {
       id: fact.frontmatter.id,
       scope: fact.frontmatter.scope,
@@ -231,6 +290,7 @@ export async function krimtoWrite(ctx: ToolContext, input: WriteInput): Promise<
       absolute_path: absolutePath,
       hint,
       commit_sha: null,
+      ...(related.length > 0 ? { related } : {}),
     };
   });
 }