opentology 0.3.0 → 0.3.2

package/dist/commands/diff.js

@@ -27,7 +27,13 @@ export function registerDiff(program) {
             for (const triple of result.removed) {
                 console.log(pc.red(`- ${triple}`));
             }
-            console.log(`\n${result.added.length} added, ${result.removed.length} removed, ${result.unchanged} unchanged`);
+            const addedLabel = result.truncated && result.addedCount > result.added.length
+                ? `${result.added.length}/${result.addedCount} added (truncated)`
+                : `${result.addedCount} added`;
+            const removedLabel = result.truncated && result.removedCount > result.removed.length
+                ? `${result.removed.length}/${result.removedCount} removed (truncated)`
+                : `${result.removedCount} removed`;
+            console.log(`\n${addedLabel}, ${removedLabel}, ${result.unchanged} unchanged`);
         }
         catch (err) {
             const message = err.message;

package/dist/lib/deep-scan-triples.js

@@ -75,11 +75,11 @@ export function generateSymbolTriples(result) {
         }
     }
     for (const call of result.methodCalls) {
-        // Method calls reference by class.method pattern — generate a simple triple
-        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}calls> <urn:call:${encodeSegment(call.callee)}> .`);
-        // Store caller/callee names for queryability
-        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}title> "${esc(call.caller)}" .`);
-        triples.push(`<urn:call:${encodeSegment(call.callee)}> <${OTX}title> "${esc(call.callee)}" .`);
+        const callUri = `urn:call:${encodeSegment(call.caller)}--${encodeSegment(call.callee)}`;
+        triples.push(`<${callUri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}MethodCall> .`);
+        triples.push(`<${callUri}> <${OTX}callerSymbol> "${esc(call.caller)}" .`);
+        triples.push(`<${callUri}> <${OTX}calleeSymbol> "${esc(call.callee)}" .`);
+        triples.push(`<${callUri}> <${OTX}title> "${esc(call.caller)} -> ${esc(call.callee)}" .`);
     }
     return triples;
 }
@@ -96,6 +96,8 @@ export async function deleteExistingSymbols(adapter, graphUri, modulePaths) {
         const modUri = moduleUri(modPath);
         await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${graphUri}> { ?s <${OTX}definedIn> <${modUri}> . ?s ?p ?o } }`);
     }
+    // Clean up MethodCall triples (no definedIn link, so delete all and re-insert)
+    await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${graphUri}> { ?s a <${OTX}MethodCall> . ?s ?p ?o } }`);
 }
 export async function pushSymbolTriples(adapter, graphUri, result) {
     // Collect all module paths for scoped delete

package/dist/lib/embedded-adapter.d.ts

@@ -18,10 +18,13 @@ export declare class EmbeddedAdapter implements StoreAdapter {
         turtle?: string;
         where?: string;
     }): Promise<void>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/lib/embedded-adapter.js

@@ -148,7 +148,7 @@ export class EmbeddedAdapter {
             throw new Error('deleteTriples: either options.turtle or options.where must be provided');
         }
     }
-    async diffGraph(graphUri, localTurtle) {
+    async diffGraph(graphUri, localTurtle, limit = 50) {
         const localQuads = await parseTurtle(localTurtle);
         const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
         // Get remote quads from the store
@@ -158,10 +158,18 @@ export class EmbeddedAdapter {
             const n3q = wasmQuadToN3Quad(q);
             remoteSet.add(`${termToSparql(n3q.subject)} ${termToSparql(n3q.predicate)} ${termToSparql(n3q.object)}`);
         }
-        const added = [...localSet].filter((t) => !remoteSet.has(t));
-        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const allAdded = [...localSet].filter((t) => !remoteSet.has(t));
+        const allRemoved = [...remoteSet].filter((t) => !localSet.has(t));
         const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
-        return { added, removed, unchanged };
+        const truncated = allAdded.length > limit || allRemoved.length > limit;
+        return {
+            added: allAdded.slice(0, limit),
+            removed: allRemoved.slice(0, limit),
+            unchanged,
+            addedCount: allAdded.length,
+            removedCount: allRemoved.length,
+            truncated,
+        };
     }
     async getSchemaOverview(graphUri) {
         const tripleCount = await this.getGraphTripleCount(graphUri);

package/dist/lib/http-adapter.d.ts

@@ -14,10 +14,13 @@ export declare class HttpAdapter implements StoreAdapter {
         turtle?: string;
         where?: string;
     }): Promise<void>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/lib/http-adapter.js

@@ -115,7 +115,7 @@ export class HttpAdapter {
             throw new Error('deleteTriples: either options.turtle or options.where must be provided');
         }
     }
-    async diffGraph(graphUri, localTurtle) {
+    async diffGraph(graphUri, localTurtle, limit = 50) {
         const localQuads = await parseTurtle(localTurtle);
         const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
         // Fetch remote quads via CONSTRUCT
@@ -125,10 +125,18 @@ export class HttpAdapter {
             ? await parseTurtle(remoteTurtle)
             : [];
         const remoteSet = new Set(remoteQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
-        const added = [...localSet].filter((t) => !remoteSet.has(t));
-        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const allAdded = [...localSet].filter((t) => !remoteSet.has(t));
+        const allRemoved = [...remoteSet].filter((t) => !localSet.has(t));
         const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
-        return { added, removed, unchanged };
+        const truncated = allAdded.length > limit || allRemoved.length > limit;
+        return {
+            added: allAdded.slice(0, limit),
+            removed: allRemoved.slice(0, limit),
+            unchanged,
+            addedCount: allAdded.length,
+            removedCount: allRemoved.length,
+            truncated,
+        };
     }
     async getSchemaOverview(graphUri) {
         const tripleCount = await this.getGraphTripleCount(graphUri);

package/dist/lib/store-adapter.d.ts

@@ -34,10 +34,13 @@ export interface StoreAdapter {
     }): Promise<void>;
     getGraphTripleCount(graphUri: string): Promise<number>;
     exportGraph(graphUri: string): Promise<string>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/mcp/server.js

@@ -269,12 +269,13 @@ async function handleDiff(args) {
     if (!content) {
         throw new Error('content (Turtle) is required');
     }
+    const limit = typeof args.limit === 'number' ? args.limit : 50;
     const { config, graphUri } = resolveConfig({
         graphUri: args.graphUri,
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
-    return await adapter.diffGraph(graphUri, content);
+    return await adapter.diffGraph(graphUri, content, limit);
 }
 async function handleGraphList(_args) {
     const config = loadConfig();
@@ -354,9 +355,11 @@ async function handleInfer(args) {
     if (clear) {
         await snapshotGraph(adapter, config, graphUri);
         await clearInferences(adapter, graphUri);
+        await persistGraph(adapter, config, graphUri);
         return { success: true, cleared: true };
     }
     const result = await materializeInferences(adapter, graphUri);
+    await persistGraph(adapter, config, graphUri);
     return result;
 }
 async function handleContextScan(args) {
@@ -389,7 +392,7 @@ async function handleContextScan(args) {
             pushStats,
             _experimental: true,
             _hint: pushStats
-                ? `Symbol triples pushed: ${pushStats.triplesInserted} triples in ${pushStats.batchCount} batches. Query with: SELECT ?c WHERE { ?c a otx:Class ; otx:definedIn <urn:module:...> }`
+                ? `Symbol triples pushed: ${pushStats.triplesInserted} triples in ${pushStats.batchCount} batches. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Functions in a module: SELECT ?f ?name WHERE { ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
                 : 'Deep scan completed but triple push failed. Use push manually with the generated triples.',
         };
     }
@@ -603,6 +606,7 @@ async function handleContextInit(args) {
         moduleStats,
         dependencyHint,
         hooksAutoInstalled: hooksChanged,
+        scanSuggestion: 'Run context_scan to populate the knowledge graph. Use depth="module" for file-level dependencies, or depth="symbol" (with includeMethodCalls=true) for class/function/call-level analysis. The symbol scan enables queries like "which functions call persistGraph?" from the graph.',
     };
 }
 async function handleContextLoad() {
@@ -1086,7 +1090,7 @@ export async function startMcpServer() {
             },
             {
                 name: 'diff',
-                description: 'Compare local Turtle content against the remote graph. Returns added triples (in local but not remote), removed triples (in remote but not local), and count of unchanged triples.',
+                description: 'Compare local Turtle content against the remote graph. Returns added triples (in local but not remote), removed triples (in remote but not local), and count of unchanged triples. Output is limited to avoid blowing up LLM context windows.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1094,6 +1098,10 @@ export async function startMcpServer() {
                             type: 'string',
                             description: 'Turtle (RDF) content to compare against the remote graph',
                         },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of added/removed triples to return (default: 50). Total counts are always included.',
+                        },
                         graph: {
                             type: 'string',
                             description: 'Logical graph name (as created by graph_create). Resolves to a graph URI via config.',
@@ -1408,9 +1416,12 @@ export async function startMcpServer() {
                 case 'context_sync': {
                     const syncConfig = loadConfig();
                     const syncContextUri = `${syncConfig.graphUri}/context`;
+                    const syncSessionsUri = `${syncConfig.graphUri}/sessions`;
                     const syncAdapter = await createReadyAdapter(syncConfig);
                     await snapshotGraph(syncAdapter, syncConfig, syncContextUri);
                     result = await syncContext(syncConfig, process.cwd());
+                    await persistGraph(syncAdapter, syncConfig, syncContextUri);
+                    await persistGraph(syncAdapter, syncConfig, syncSessionsUri);
                     break;
                 }
                 case 'rollback':

package/dist/templates/claude-md-context.js

@@ -7,7 +7,10 @@ export function generateContextSection(projectId, graphUri) {
     return `${MARKER_BEGIN}
 ## Context Management — OpenTology
 
-This project uses OpenTology as its project context graph.
+This project uses OpenTology as its knowledge graph — treat it as the project's **long-term memory**.
+Before reading source files, grep-searching, or making assumptions, **query the graph first**.
+It holds architectural decisions, resolved issues, reusable patterns, module dependencies,
+symbol-level call graphs, and session history. Prefer graph knowledge over re-deriving facts from code.
 
 ### Graph Structure
 
@@ -26,6 +29,12 @@ This project uses OpenTology as its project context graph.
 | \`otx:Knowledge\` | Reusable knowledge |
 | \`otx:Session\` | Session logs |
 | \`otx:Pattern\` | Recurring patterns/conventions |
+| \`otx:Module\` | Source file module |
+| \`otx:Class\` | Class definition (symbol scan) |
+| \`otx:Interface\` | Interface definition (symbol scan) |
+| \`otx:Function\` | Function definition (symbol scan) |
+| \`otx:Method\` | Method definition (symbol scan) |
+| \`otx:MethodCall\` | Call relationship between symbols (symbol scan) |
 
 | Property | Range | Description |
 |----------|-------|-------------|
@@ -36,6 +45,11 @@ This project uses OpenTology as its project context graph.
 | \`otx:reason\` | string | Decision rationale |
 | \`otx:nextTodo\` | string | Next action item |
 | \`otx:relatedTo\` | resource | Related entity |
+| \`otx:dependsOn\` | Module | Module import dependency |
+| \`otx:definedIn\` | Module | Which module a symbol belongs to |
+| \`otx:callerSymbol\` | string | Caller in a MethodCall |
+| \`otx:calleeSymbol\` | string | Callee in a MethodCall |
+| \`otx:calls\` | resource | Call relationship |
 
 ### When to Record
 
@@ -107,13 +121,48 @@ If impact is **high**, inform the user of affected modules and get confirmation
 
 #### Searching the Knowledge Graph
 
-Use \`query\` with SPARQL to find anything in the project graph:
+Use \`query\` with SPARQL to find anything in the project graph. **Always query the graph before reading source files** when investigating code structure, dependencies, or call relationships:
+
 - **Decisions**: \`?s a otx:Decision\` — why architectural choices were made
 - **Issues**: \`?s a otx:Issue ; otx:status "open"\` — known bugs and their status
 - **Knowledge**: \`?s a otx:Knowledge\` — reusable patterns and lessons learned
 - **Sessions**: query the sessions graph for past work logs and next TODOs
 - **Modules**: \`?s a otx:Module\` — all scanned source modules and their dependencies (\`otx:dependsOn\`)
 - **Symbols**: \`?s a otx:Class\`, \`otx:Interface\`, \`otx:Function\`, \`otx:Method\` — code-level entities (available after symbol-depth scan)
+- **Call graph**: \`?s a otx:MethodCall\` — who calls whom (available after symbol scan with \`includeMethodCalls=true\`)
+
+\`\`\`sparql
+# Functions in a specific module
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?name WHERE {
+  GRAPH <${contextUri}> {
+    ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> .
+  }
+}
+
+# Who calls a specific function?
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?caller WHERE {
+  GRAPH <${contextUri}> {
+    ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee .
+    FILTER(CONTAINS(?callee, "persistGraph"))
+  }
+}
+
+# Module dependency chain (what depends on a module?)
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?dependent WHERE {
+  GRAPH <${contextUri}> {
+    ?dependent otx:dependsOn+ <urn:module:src/lib/store-adapter> .
+  }
+}
+\`\`\`
+
+#### Post-Edit Graph Update
+
+After significant code changes (new files, renamed functions, changed dependencies), run \`context_scan\` to keep the knowledge graph in sync:
+- \`depth="module"\` — fast, updates file-level imports
+- \`depth="symbol"\` with \`includeMethodCalls=true\` — thorough, updates class/function/call graph
 
 #### Other Useful Tools
 

package/dist/templates/otx-ontology.d.ts

@@ -1 +1 @@
-export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty ; rdfs:domain otx:Method ; rdfs:range otx:Method .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";
+export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\notx:MethodCall a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty .\notx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";

package/dist/templates/otx-ontology.js

@@ -30,12 +30,15 @@ otx:Class a owl:Class .
 otx:Interface a owl:Class .
 otx:Function a owl:Class .
 otx:Method a owl:Class .
+otx:MethodCall a owl:Class .
 
 otx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .
 otx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .
 otx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .
 otx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .
-otx:calls a owl:ObjectProperty ; rdfs:domain otx:Method ; rdfs:range otx:Method .
+otx:calls a owl:ObjectProperty .
+otx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
+otx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
 otx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .
 otx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentology",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {