Memory & File Storage Management

Relevant source files

The following files were used as context for generating this wiki page:

• backend/src/memory-adapter.ts
• backend/src/file-adapter.ts
• backend/src/handler.ts
• src/main.ts
• src/renderer.tsx
• instructions/design-backend-prompt.txt

The Memory & File Storage Management system in JARVIS provides the persistence layer required for a personalized AI experience. It is divided into two primary concerns: Persistent Long-Term Memory, which stores operator preferences and structured facts, and Local File/RAG Management, which allows the assistant to explore and query the local project environment using Retrieval-Augmented Generation (RAG).

The system follows a strict local-first architecture, ensuring that all memory items and file indices are stored on the operator's machine rather than in the cloud. This architecture supports the "Pair before personalizing" security principle, where sensitive memory and filesystem routes are only exposed via authenticated loopback connections.

Sources: instructions/design-backend-prompt.txt:54-61, backend/src/handler.ts:474-478

---

Architecture Overview

The system architecture utilizes a layered approach where the frontend renderer communicates with a TypeScript backend service via an Electron IPC bridge.

The diagram shows the data flow from the user interface through the Electron IPC bridge to the specialized backend adapters.
Sources: src/main.ts:705-728, backend/src/handler.ts:371-385, src/renderer.tsx:2100-2120

---

Long-Term Memory Management

The Long-Term Memory system allows JARVIS to persist user-specific context across sessions. Memory items are categorized to help the LLM distinguish between hard facts and subjective preferences.

Memory Categories

Memory items are classified into three types defined by the JarvisMemoryCategory contract:

• operator_preference: Subjective settings like preferred coding style or language.
• structured_fact: Objective data such as the operating system or user birthday.
• semantic_document: Larger pieces of information or notes.

Sources: backend/src/memory-adapter.ts:16-24, instructions/design-backend-prompt.txt:54-58

Persistence Logic

The FileJarvisMemoryAdapter implements the JarvisMemoryAdapter interface using simple JSON storage. By default, it looks for .jarvis-memory.json in the working directory or uses the path defined in the JARVIS_MEMORY_FILE_PATH environment variable.

Feature	Implementation Detail
Storage Format	Indented JSON
Concurrency	Atomic read/write using node:fs/promises
Initial State	Populated with defaults (e.g., Operator Name: "Ed") if file is missing
Provenance	Tracks origin (e.g., system_default, manual_entry, voice_command)

Sources: backend/src/memory-adapter.ts:39-81, backend/src/memory-adapter.ts:114-118

The sequence diagram illustrates how the AI assistant uses tool calls to retrieve information from the persistent memory storage.
Sources: backend/src/handler.ts:251-260, backend/src/memory-adapter.ts:88-103

---

Local File System & RAG

The FileJarvisFileAdapter enables the assistant to interact with the project's source code and documentation. It includes security safeguards and a basic scoring algorithm for Retrieval-Augmented Generation.

Security and Constraints

To prevent unauthorized access, the adapter enforces several constraints:

1. Workspace Isolation: All paths are resolved relative to a workspaceRoot and checked to ensure they do not escape that directory.
2. Extension Allowlist: Only specific file types (e.g., .ts, .tsx, .md, .json, .py) can be read.
3. Size Limits: Individual files exceeding 500KB are blocked from being read to prevent memory exhaustion.
4. Ignored Directories: Common heavy or metadata folders like node_modules, .git, and dist are excluded from scans.

Sources: backend/src/file-adapter.ts:32-55, backend/src/file-adapter.ts:98-105

RAG Implementation

The RAG system uses a keyword-based scoring mechanism to find relevant code or document snippets.

• Chunking: Files are split into chunks of approximately 15 lines.
• Scoring:
  • +2 points per keyword match within the chunk content.
  • +3 points if the keyword is found in the file path.
• Ranking: Chunks are sorted by score, and the top results (defaulting to 5) are returned to the model.

Sources: backend/src/file-adapter.ts:116-168

---

IPC and API Integration

The system is exposed through several API endpoints and Electron IPC handlers, enabling both the UI and the AI model to interact with storage.

API Endpoints (Backend Service)

Method	Endpoint	Description
GET	/v1/memory	Retrieves memory items based on category or search terms.
POST	/v1/memory	Adds a new JarvisMemoryItem.
DELETE	/v1/memory/:id	Deletes a specific memory item.
GET	/v1/files/list	Lists files in a directory within the workspace.
POST	/v1/files/rag	Performs a keyword search across project files for RAG.

Sources: backend/src/handler.ts:468-472, backend/src/handler.ts:602-612, backend/src/handler.ts:634-645

IPC Handlers (Main Process)

The Electron main process bridges these service calls to the frontend:

• jarvis:get-memory-items
• jarvis:add-memory-item
• jarvis:query-rag
• jarvis:list-files

Sources: src/main.ts:705-725

---

Data Structures

JarvisMemoryItem

{
  id: string;
  category: "operator_preference" | "structured_fact" | "semantic_document";
  key: string;
  value: string;
  provenance: string;
  createdAt: string;
  updatedAt: string;
}

Sources: backend/src/memory-adapter.ts:108-118, instructions/design-backend-prompt.txt:54-58

JarvisRagChunk

{
  filePath: string;
  lineStart: number;
  lineEnd: number;
  content: string;
  score: number;
}

Sources: backend/src/file-adapter.ts:14-20

---

Conclusion

The Memory & File Storage Management system forms the "Second Brain" of JARVIS. By combining lightweight JSON-based persistence for personal facts with a restricted, chunk-based RAG system for local files, JARVIS can provide highly contextual responses while maintaining complete data sovereignty for the user. All storage operations are performed locally, adhering to the project's core privacy and security principles.

Sources: instructions/design-backend-prompt.txt:130-136, backend/src/handler.ts:474-478