AI-Powered Personal Knowledge Base: Local Markdown + AI Coding Assistant

I. Introduction: Why Bring an AI Coding Assistant into Your Notes Repository

There is no shortage of “knowledge management” tools. For most people, though, the real problem is different: capturing feels great, but finding things later is hard. Read-later folders fill up with hundreds of articles, and temporary notes end up scattered across devices. Then, when you actually need to write a proposal or prepare a report, you can’t remember what you saved a few months ago.

A note-taking system built around local Markdown files solves two basic questions: who owns the data, and can it be moved elsewhere? Even so, it still has three weaknesses:

• Search depends on keywords: if you can’t remember the exact wording you used, you probably won’t find the note.
• Processing is manual: filing notes, tagging them, writing summaries and building tables of contents are all done by hand.
• Knowledge isn’t connected: notes have few links to one another, so it’s hard to build a coherent body of knowledge.

Command-line AI coding assistants were built for code repositories. Their core capabilities include reading files, searching code, editing files according to rules and running commands, and these fill exactly those gaps. If you point one at your notes repository and treat it as a “working directory,” you can use natural language to organize, summarize, link and search your notes.

This article walks through the whole approach in order: solution design → environment preparation → installation and configuration → advanced practices.

II. Solution Design: A Five-Layer Architecture and Three Principles

2.1 Overall Architecture

Layer	Components	Responsibility
Storage	A local Markdown folder, with notes and attachments (such as images) stored separately	Single source of truth for raw data
Sync	Version control, or cloud storage/NAS (optional)	Access from multiple devices, history rollback and backup
Editing	A local Markdown note app and its plugins	Day-to-day reading, editing, backlinks and graph view
Processing	The AI assistant built into the note app, plus the command-line coding assistant	Organizing, summarizing, linking and batch jobs
Inference	A cloud LLM API, or an open model deployed locally	Understanding and generation

The overall data flow is:

Capture (Editing) → Normalize (Processing) → Index (Processing) → Process (Inference) → Retrieve → Output back to the Editing layer

2.2 Three Design Principles

1. Plain text first. Store all content as Markdown, and express metadata with frontmatter (a YAML header). Plain-text files can be opened in any editor, tracked precisely by version control and parsed directly by AI tools.
2. A clear division of labor between human and machine. AI handles repetitive work such as scanning, summarizing, rewriting and linking notes. You decide what is worth keeping, how it should be categorized and whether the facts are accurate. AI is always an “assistant,” never the “author.”
3. Safe and controlled. Notes stay on your machine. Only content that genuinely needs it is sent to a model service. The assistant gets only limited access to the file system, and no keys are ever committed to the repository.

III. Environment Preparation: Runtime, Model Backend and Repository Skeleton

3.1 Runtime

Command-line AI coding assistants are usually built on a JavaScript runtime such as Node.js. Keep the following in mind when installing:

• Version: use a currently supported LTS (Long-Term Support) release.
• Installation method: on macOS, you can install Node.js with a package manager such as Homebrew. On Windows, you can download the official installer or install it inside WSL (Windows Subsystem for Linux) as you would in a Unix-like environment.
• Registry: if your network is slow or restricted, you can temporarily point npm at an alternative registry to speed up downloads. The command below applies only to the current terminal session, which makes it suitable for one-off installations:

# Windows PowerShell: install from a temporary registry for this session only, without changing system-wide settings
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmjs.org

• Verify the environment: after installation, run node -v and npm -v to confirm that version numbers are printed correctly.

3.2 Model Backend

The assistant itself only “orchestrates tools.” The actual understanding and generation are handled by a backend large language model. The assistant usually calls models through an OpenAI-compatible interface, and the configuration requires three key pieces of information:

• Base URL (endpoint): provided in the cloud provider’s API documentation.
• API key: created in the provider’s console. Check the console for the available quota, the list of models and any rate limits.
• Model name: must exactly match the model ID provided by the platform, including capitalization.

Cloud services require no infrastructure to operate, and most major cloud platforms offer APIs that are compatible with the OpenAI protocol. For data-sensitive scenarios, or when you need to work offline, you can run open models locally with tools such as Ollama or LM Studio and connect to them through a local OpenAI-compatible endpoint. The trade-off is that quality and speed depend on your hardware.

3.3 Repository Skeleton

Here, “repository” means a notes directory managed by version control or a sync tool. Use numeric prefixes to fix the folder order, and keep “raw material that hasn’t been organized yet” separate from “knowledge that has settled”:

my-vault/
├── AGENTS.md           # Context and rules file for the assistant
├── 00_Inbox/           # To be organized: web clippings, quick ideas
├── 10_Notes/           # Permanent notes: one idea per note
├── 20_Daily/           # Daily notes and weekly reviews
├── 30_Projects/        # Project material
├── 90_Assets/          # Attachments such as images
└── 99_Templates/       # Note templates

IV. Installing a Local Markdown Note App and the AI Assistant Plugin

4.1 Installing the Note App

Download the installer for your operating system from the official website and double-click it to install. The core features are free. This type of app is a good choice for three reasons:

• It stores notes as local Markdown files, so they aren’t locked into a cloud service.
• It has a rich plugin ecosystem you can extend as needed.
• It natively supports [[wikilinks]] and a relationship graph.

When you start using it, create a Vault (notes repository) that points to the directory from Section 3.3.

4.2 Enabling Third-Party Plugins

1. Open Settings (usually at the bottom-left), go to “Third-party plugins” and turn off “Restricted mode.” You can then install community plugins. Even so, only install plugins from trusted sources that are actively maintained.
2. In the “Community plugins” browser, search for and install a plugin manager. Once enabled, you can use it to install beta plugins that aren’t yet listed in the official marketplace.
3. On the plugin manager’s settings page, run “Add beta plugin” and enter the target plugin’s Git repository URL to install it.
4. Go back to the third-party plugins list and enable the plugin.

4.3 Configuring the Assistant Plugin

The first time you use it, the plugin usually asks for the installation path of the command-line coding assistant, or lets you install it directly from the settings. After that, you can open a chat panel in the sidebar. Recommended settings:

• Set the Vault root as the assistant’s working directory, so it can read and write the entire library.
• If you want, turn off manual confirmation for each write operation, but keep confirmation prompts for high-risk actions such as deleting and moving files.
• Save frequently used instructions (such as “Tidy up today’s inbox”) as custom commands to avoid typing them repeatedly.

4.4 Security Checklist

• Only install plugins from official or trusted sources, and pay attention to the permissions they request.
• After the note app updates, if a plugin temporarily fails to load, check version compatibility first instead of blindly downgrading.
• If your Vault uses version control, any file containing an API key must be on the ignore list.

V. Installing the Coding Assistant and Configuring Multiple Model Backends

5.1 Installing the Command-Line Assistant

Once your runtime is ready, run one command in the terminal to install it globally:

# Global install (requires Node.js 18 or later)
npm install -g @anthropic-ai/claude-code
# Verify the installation
claude --version

You can also use the official native install script. This method doesn’t depend on Node.js and configures automatic updates for you. For security reasons, check where the script comes from before running it.

5.2 Creating and Verifying a Model Configuration

To avoid repeatedly typing environment variables in the terminal, you can use a third-party desktop tool to manage your provider configurations in one place. Take CC Switch as an example:

1. Download the installer from the GitHub Releases page: on macOS, choose the .dmg file; on Windows, choose .msi (or .exe if you don’t have administrator rights).
2. Launch the tool and click “+” to create a new configuration.
3. Select the DeepSeek preset, or choose a custom provider.
4. Paste the API key you obtained from the DeepSeek open platform.

5. Add two models:

   • one general-purpose chat model (such as deepseek-chat);
   • one deep-reasoning model (such as deepseek-reasoner), to be used for the main conversation.

   Check the platform documentation for the exact model IDs.

6. Save and launch. The terminal will start the assistant with this configuration. To confirm the whole chain works, ask it to read the README and summarize it.

If you have already configured Claude Code to use DeepSeek by following an earlier setup guide, you can skip to Section 6.

The installation and configuration steps in this article were tested with Claude Code 2.1.207, CC Switch 3.16.1 and Obsidian 1.12.7. See the end of the article for the test environment.

5.3 How the Configuration Works

A configuration management tool essentially maintains environment variables and configuration files for you, such as:

• ANTHROPIC_BASE_URL: the endpoint that requests are forwarded to;
• ANTHROPIC_AUTH_TOKEN: the API key;
• ANTHROPIC_MODEL: the main model;
• ANTHROPIC_DEFAULT_HAIKU_MODEL: the lightweight model used for background tasks such as file summaries and title generation, which also helps control costs.

Understanding this layer makes it easier to troubleshoot outside the tool.

5.4 Connecting a Cloud Notes MCP Server

If most of your knowledge material lives in a third-party cloud notes service, you can connect it through that service’s official MCP server:

# Option 1: add it interactively
claude mcp add cloud-notes \
  --transport http \
  --header "Authorization: Bearer <YOUR_TOKEN>" \
  https://<CLOUD_NOTES_MCP_SERVER_URL>
# Option 2: edit the configuration file directly
# Windows: %USERPROFILE%\.claude.json
# macOS / Linux: ~/.claude.json

{
  "mcpServers": {
    "cloud-notes": {
      "type": "http",
      "url": "https://<CLOUD_NOTES_MCP_SERVER_URL>",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Check the official documentation of your cloud notes service for the server URL and how to obtain a token. Once the connection succeeds, the assistant can search, read and write your cloud notes.

VI. Advanced: Getting AI to Truly “Understand” Your Knowledge Base

6.1 Establishing a “Shared Language” with a Rules File

Create AGENTS.md in the root of your Vault. The assistant reads it every time it starts and treats it as a unified set of “working rules” for the whole library:

# Knowledge Base Assistant Rules
## Role
You are the organizing and retrieval assistant for this knowledge base, serving technical learning and work retrospectives.
## Directory conventions
- 00_Inbox: unprocessed material; you may add to it, but do not delete from it
- 10_Notes: permanent notes, one idea per note; the filename states the core point
- 20_Daily: daily notes and weekly reviews
- 30_Projects: project material
- 90_Assets: images and attachments
- 99_Templates: note templates
## frontmatter fields
type (seed/growing/evergreen), status, tags, created, updated, source
## Writing conventions
- Keep permanent notes to 300–800 words; state the conclusion first, then develop the argument
- Always cite the source and retrieval date for external content
- Link to existing notes with [[wikilinks]] when a concept first appears
- Write tags in lowercase English, using / to separate levels, e.g., tech/ai/rag
## Operating constraints
- Before any batch modification, output a change plan and wait for my confirmation before executing it
- Do not invent quotations, data or sources; mark uncertain content as "to be verified"
- When deleting or moving files, list each item and explain why

The value of rules is consistency: the same instruction produces output in a consistent style, no matter who runs it or when.

6.2 Standardizing frontmatter Metadata

Metadata is both the “index key” for AI retrieval and the basis for processing changes in version control. Example template:

---
type: permanent
status: evergreen
tags: [tech/ai/rag, concept/chunking]
created: 2025-03-18
updated: 2025-05-02
source: "A conference paper, 2024"
confidence: 0.8
---

The status field shows how mature a note is, using three levels: seed (raw material), growing, and evergreen (stable knowledge that has been verified).

6.3 Two Retrieval Approaches: On-Demand Reading and Vector Indexing

• On-demand reading: the assistant uses tools such as Grep and Glob to locate files first and then read the relevant ones closely. It’s simple to set up and usually sufficient for up to a few thousand notes.
• Vector indexing: notes are split into chunks, converted into embeddings and stored in a vector database, then retrieved by semantic similarity. This approach is better suited to libraries with more than ten thousand notes that need semantic search across notes.

A minimal implementation sketch is shown below. This is illustrative code, and you can replace the tokenizer and embedding scheme as needed:

from pathlib import Path
VAULT = Path("my-vault")
def build_index():
    records = []
    for md in VAULT.rglob("*.md"):
        if any(part in {"90_Assets", "99_Templates"} for part in md.parts):
            continue
        text = md.read_text(encoding="utf-8")
        meta, body = parse_frontmatter(text)      # Parse the YAML header
        for i, chunk in enumerate(split_text(body, size=800, overlap=100)):
            records.append({
                "id": f"{md.as_posix()}#{i}",
                "path": md.as_posix(),
                "title": meta.get("title", md.stem),
                "tags": meta.get("tags", []),
                "text": chunk,
            })
    upsert_to_vector_db(records)                  # Upsert by id, so re-runs only update changed notes

At query time, merging and reranking keyword search results and vector search results usually retrieves more relevant content than either method alone.

6.4 Controlling Costs on Three Levels

• Use different models for different tasks: run lightweight background tasks on a low-cost model, and reserve a more capable model for the main conversation.
• Process incrementally: handle only new or modified notes. Record a content hash at the top of each note, and skip any note whose hash hasn’t changed.
• Reuse cached results: cache stable outputs such as summaries and tags, and read them directly on re-runs.

VII. Troubleshooting Common Problems

Symptom	Likely cause	Fix
Terminal says the claude command can’t be found	The install directory isn’t in PATH, or the current terminal is still using the old configuration	Open a new terminal window; if that doesn’t help, check your environment variables
The assistant reports an authentication failure or says the model doesn’t exist	The API key has expired or is invalid, you’re out of quota, or the model ID is misspelled	Check the key and model name in the provider’s console
The old model is still used after switching providers	Leftover old environment variables	Clear them and restart the tool
A plugin doesn’t appear after installation	It isn’t enabled, or the version is incompatible	Check whether it’s enabled; if necessary, download an offline package from the Releases page and extract it into the plugin directory

VIII. Conclusion and Recommended Next Steps

The bottleneck in a personal knowledge base is often not capturing notes, but organizing them and retrieving them later. The key points of this approach come down to four:

• Keep data under your control with local Markdown.
• Use a rules file to keep AI behavior consistent.
• Use metadata and indexes to support efficient retrieval.
• Manage permissions and keys to protect your security boundary.

Start small: tidy up ten old notes in 00_Inbox first and see how well the assistant summarizes them. Then gradually expand to use cases such as weekly reviews and project archiving. Tools will keep changing and configurations will evolve, but the principles of data ownership, clear rules and security will remain valuable over the long term.

---

Test environment: Windows 11 Home (25H2); Claude Code 2.1.207; CC Switch 3.16.1; Obsidian 1.12.7; DeepSeek API (OpenAI-compatible endpoint).